@olaservo/skill-jack-mcp 0.2.0 → 0.3.0

package/README.md

@@ -2,12 +2,12 @@
 
 An MCP server that jacks [Agent Skills](https://agentskills.io) directly into your LLM's brain.
 
-> **Recommended:** For best results, use an [MCP client](https://modelcontextprotocol.io/clients) that supports server instructions. This allows the LLM to see available skills in its system prompt, enabling automatic skill discovery and activation. Without this support, the model will still be able to call these tools, but you might need to provide more explicit instructions on what skills are available and the intended activation patterns.
+> **Recommended:** For best results, use an MCP client that supports `tools/listChanged` notifications (e.g., Claude Code). This enables dynamic skill discovery - when skills are added or modified, the client automatically refreshes its understanding of available skills.
 
 ## Features
 
-- **Skill Discovery** - Discovers skills from a configured directory at startup
-- **Server Instructions** - Injects skill metadata into the system prompt (for clients supporting instructions)
+- **Dynamic Skill Discovery** - Watches skill directories and automatically refreshes when skills change
+- **Tool List Changed Notifications** - Sends `tools/listChanged` so clients can refresh available skills
 - **Skill Tool** - Load full skill content on demand (progressive disclosure)
 - **MCP Resources** - Access skills via `skill://` URIs with batch collection support
 - **Resource Subscriptions** - Real-time file watching with `notifications/resources/updated`
@@ -59,26 +59,37 @@ skill-jack-mcp "C:/Users/you/skills"
 
 ## How It Works
 
-The server implements the [Agent Skills](https://agentskills.io) progressive disclosure pattern:
+The server implements the [Agent Skills](https://agentskills.io) progressive disclosure pattern with dynamic updates:
 
-1. **At startup**: Discovers skills from configured directories
-2. **On connection**: Server instructions (with skill metadata) are sent in the initialize response
-3. **On tool call**: Agent calls `skill` tool to load full SKILL.md content
+1. **At startup**: Discovers skills from configured directories and starts file watchers
+2. **On connection**: Skill tool description includes available skills metadata
+3. **On file change**: Re-discovers skills, updates tool description, sends `tools/listChanged`
+4. **On tool call**: Agent calls `skill` tool to load full SKILL.md content
+5. **As needed**: Agent calls `skill-resource` to load additional files
 
 ```
 ┌─────────────────────────────────────────────────────────┐
 │ Server starts                                            │
 │   • Discovers skills from configured directories         │
-│   • Generates instructions with skill metadata           │
+│   • Starts watching for SKILL.md changes                 │
 │   ↓                                                      │
 │ MCP Client connects                                      │
-│   • Server instructions included in initialize response  │
+│   • Skill tool description includes available skills     │
 │   ↓                                                      │
-│ LLM sees skill metadata in system prompt                 │
+│ LLM sees skill metadata in tool description              │
+│   ↓                                                      │
+│ SKILL.md added/modified/removed                          │
+│   • Server re-discovers skills                           │
+│   • Updates skill tool description                       │
+│   • Sends tools/listChanged notification                 │
+│   • Client refreshes tool definitions                    │
 │   ↓                                                      │
 │ LLM calls "skill" tool with skill name                   │
 │   ↓                                                      │
 │ Server returns full SKILL.md content                     │
+│   ↓                                                      │
+│ LLM calls "skill-resource" for additional files          │
+│   • Scripts, snippets, references, assets, etc.          │
 └─────────────────────────────────────────────────────────┘
 ```
 
@@ -138,7 +149,6 @@ Skills are also accessible via MCP [Resources](https://modelcontextprotocol.io/s
 
 | URI | Returns |
 |-----|---------|
-| `skill://` | All SKILL.md contents (collection) |
 | `skill://{name}` | Single skill's SKILL.md content |
 | `skill://{name}/` | All files in skill directory (collection) |
 | `skill://{name}/{path}` | Specific file within skill |
@@ -178,7 +188,7 @@ Clients can subscribe to resources for real-time updates when files change.
 
 Protections in place:
 - Path traversal prevention (symlink-aware)
-- File size limits (10MB max)
+- File size limits (1MB default, configurable via `MAX_FILE_SIZE_MB` env var)
 - Directory depth limits
 - Skill content is confined to configured directories
 
@@ -186,9 +196,18 @@ Not protected against:
 - Malicious content within trusted skill directories
 - Prompt injection via skill instructions (skills can influence LLM behavior by design)
 
-## Server Instructions Format
+## Dynamic Skill Discovery
+
+The server watches skill directories for changes. When SKILL.md files are added, modified, or removed:
+
+1. Skills are re-discovered from all configured directories
+2. The `skill` tool's description is updated with current skill names and metadata
+3. `tools/listChanged` notification is sent to connected clients
+4. Clients that support this notification will refresh tool definitions
+
+## Skill Metadata Format
 
-The server generates [instructions](https://blog.modelcontextprotocol.io/posts/2025-11-03-using-server-instructions/) that include a usage preamble and skill metadata:
+The `skill` tool description includes metadata for all available skills in XML format:
 
 ```markdown
 # Skills
@@ -204,7 +223,7 @@ When a user's task matches a skill description below: 1) activate it, 2) follow
 </available_skills>
 ```
 
-These are loaded into the model's system prompt by [clients](https://modelcontextprotocol.io/clients) that support instructions.
+This metadata is dynamically updated when skills change - clients supporting `tools/listChanged` will automatically refresh.
 
 ## Skill Discovery
 

package/dist/index.js

@@ -12,12 +12,13 @@
  */
 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, generateInstructions, createSkillMap } from "./skill-discovery.js";
-import { registerSkillTool } from "./skill-tool.js";
+import { discoverSkills, createSkillMap } from "./skill-discovery.js";
+import { registerSkillTool, getToolDescription } from "./skill-tool.js";
 import { registerSkillResources } from "./skill-resources.js";
-import { createSubscriptionManager, registerSubscriptionHandlers, } from "./subscriptions.js";
+import { createSubscriptionManager, registerSubscriptionHandlers, refreshSubscriptions, } from "./subscriptions.js";
 /**
  * Subdirectories to check for skills within the configured directory.
  */
@@ -64,7 +65,6 @@ function getSkillsDirs() {
  */
 const skillState = {
     skillMap: new Map(),
-    instructions: "",
 };
 /**
  * Discover skills from multiple configured directories.
@@ -102,6 +102,129 @@ function discoverSkillsFromDirs(skillsDirs) {
     }
     return allSkills;
 }
+/**
+ * Debounce delay for skill directory changes (ms).
+ * Multiple rapid changes are coalesced into one refresh.
+ */
+const SKILL_REFRESH_DEBOUNCE_MS = 500;
+/**
+ * Refresh skills and notify clients of changes.
+ * Called when skill files change on disk.
+ *
+ * @param skillsDirs - The configured skill directories
+ * @param server - The MCP server instance
+ * @param skillTool - The registered skill tool to update
+ * @param subscriptionManager - For refreshing resource subscriptions
+ */
+function refreshSkills(skillsDirs, server, skillTool, subscriptionManager) {
+    console.error("Refreshing skills...");
+    // Re-discover all skills
+    const skills = discoverSkillsFromDirs(skillsDirs);
+    const oldCount = skillState.skillMap.size;
+    // Update shared state
+    skillState.skillMap = createSkillMap(skills);
+    console.error(`Skills refreshed: ${oldCount} -> ${skills.length} skill(s)`);
+    // Update the skill tool description with new instructions
+    skillTool.update({
+        description: getToolDescription(skillState),
+    });
+    // Refresh resource subscriptions to match new skill state
+    refreshSubscriptions(subscriptionManager, skillState, (uri) => {
+        server.server.notification({
+            method: "notifications/resources/updated",
+            params: { uri },
+        });
+    });
+    // Notify clients that tools have changed
+    // This prompts clients to call tools/list again
+    server.sendToolListChanged();
+    // Also notify that resources have changed
+    server.sendResourceListChanged();
+}
+/**
+ * Set up file watchers on skill directories to detect changes.
+ * Watches for SKILL.md additions, modifications, and deletions.
+ *
+ * @param skillsDirs - The configured skill directories
+ * @param server - The MCP server instance
+ * @param skillTool - The registered skill tool to update
+ * @param subscriptionManager - For refreshing subscriptions
+ */
+function watchSkillDirectories(skillsDirs, server, skillTool, subscriptionManager) {
+    let refreshTimeout = null;
+    const debouncedRefresh = () => {
+        if (refreshTimeout) {
+            clearTimeout(refreshTimeout);
+        }
+        refreshTimeout = setTimeout(() => {
+            refreshTimeout = null;
+            refreshSkills(skillsDirs, server, skillTool, subscriptionManager);
+        }, SKILL_REFRESH_DEBOUNCE_MS);
+    };
+    // Build list of paths to watch
+    const watchPaths = [];
+    for (const dir of skillsDirs) {
+        if (fs.existsSync(dir)) {
+            watchPaths.push(dir);
+            // Also watch standard subdirectories
+            for (const subdir of SKILL_SUBDIRS) {
+                const subPath = path.join(dir, subdir);
+                if (fs.existsSync(subPath)) {
+                    watchPaths.push(subPath);
+                }
+            }
+        }
+    }
+    if (watchPaths.length === 0) {
+        console.error("No skill directories to watch");
+        return;
+    }
+    console.error(`Watching for skill changes in: ${watchPaths.join(", ")}`);
+    const watcher = chokidar.watch(watchPaths, {
+        persistent: true,
+        ignoreInitial: true,
+        depth: 2, // Watch skill subdirectories but not too deep
+        ignored: ["**/node_modules/**", "**/.git/**"],
+        awaitWriteFinish: {
+            stabilityThreshold: 200,
+            pollInterval: 50,
+        },
+    });
+    // Watch for SKILL.md changes specifically
+    watcher.on("add", (filePath) => {
+        if (path.basename(filePath).toLowerCase() === "skill.md") {
+            console.error(`Skill added: ${filePath}`);
+            debouncedRefresh();
+        }
+    });
+    watcher.on("change", (filePath) => {
+        if (path.basename(filePath).toLowerCase() === "skill.md") {
+            console.error(`Skill modified: ${filePath}`);
+            debouncedRefresh();
+        }
+    });
+    watcher.on("unlink", (filePath) => {
+        if (path.basename(filePath).toLowerCase() === "skill.md") {
+            console.error(`Skill removed: ${filePath}`);
+            debouncedRefresh();
+        }
+    });
+    // Also watch for directory additions (new skill folders)
+    watcher.on("addDir", (dirPath) => {
+        // Check if this might be a new skill directory
+        const skillMdPath = path.join(dirPath, "SKILL.md");
+        const skillMdPathLower = path.join(dirPath, "skill.md");
+        if (fs.existsSync(skillMdPath) || fs.existsSync(skillMdPathLower)) {
+            console.error(`Skill directory added: ${dirPath}`);
+            debouncedRefresh();
+        }
+    });
+    watcher.on("unlinkDir", (dirPath) => {
+        // A skill directory was removed
+        console.error(`Directory removed: ${dirPath}`);
+        debouncedRefresh();
+    });
+}
 /**
  * Subscription manager for resource file watching.
  */
@@ -119,7 +242,6 @@ async function main() {
     // Discover skills at startup
     const skills = discoverSkillsFromDirs(skillsDirs);
     skillState.skillMap = createSkillMap(skills);
-    skillState.instructions = generateInstructions(skills);
     console.error(`Discovered ${skills.length} skill(s)`);
     // Create the MCP server
     const server = new McpServer({
@@ -127,16 +249,17 @@ async function main() {
         version: "1.0.0",
     }, {
         capabilities: {
-            tools: {},
+            tools: { listChanged: true },
             resources: { subscribe: true, listChanged: true },
         },
-        instructions: skillState.instructions,
     });
     // Register tools and resources
-    registerSkillTool(server, skillState);
+    const skillTool = registerSkillTool(server, skillState);
     registerSkillResources(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);
     // Connect via stdio transport
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/dist/skill-discovery.d.ts

@@ -28,5 +28,6 @@ export declare function generateInstructions(skills: SkillMetadata[]): string;
 export declare function loadSkillContent(skillPath: string): string;
 /**
  * Create a map from skill name to skill metadata for fast lookup.
+ * Uses first-wins behavior: if duplicate names exist, the first occurrence is kept.
  */
 export declare function createSkillMap(skills: SkillMetadata[]): Map<string, SkillMetadata>;

package/dist/skill-discovery.js

@@ -126,11 +126,19 @@ export function loadSkillContent(skillPath) {
 }
 /**
  * Create a map from skill name to skill metadata for fast lookup.
+ * Uses first-wins behavior: if duplicate names exist, the first occurrence is kept.
  */
 export function createSkillMap(skills) {
     const map = new Map();
     for (const skill of skills) {
-        map.set(skill.name, skill);
+        if (map.has(skill.name)) {
+            const existing = map.get(skill.name);
+            console.error(`Warning: Duplicate skill name "${skill.name}" found at ${skill.path} - ` +
+                `keeping first occurrence from ${existing.path}`);
+        }
+        else {
+            map.set(skill.name, skill);
+        }
     }
     return map;
 }

package/dist/skill-resources.d.ts

@@ -8,9 +8,8 @@
  * skill updates when MCP roots change.
  *
  * URI Scheme:
- *   skill://                    -> Collection: all SKILL.md contents
  *   skill://{skillName}         -> SKILL.md content (template)
- *   skill://{skillName}/        -> Collection: all files in skill
+ *   skill://{skillName}/        -> Collection: all files in skill directory
  *   skill://{skillName}/{path}  -> File within skill directory (template)
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

package/dist/skill-resources.js

@@ -8,9 +8,8 @@
  * skill updates when MCP roots change.
  *
  * URI Scheme:
- *   skill://                    -> Collection: all SKILL.md contents
  *   skill://{skillName}         -> SKILL.md content (template)
- *   skill://{skillName}/        -> Collection: all files in skill
+ *   skill://{skillName}/        -> Collection: all files in skill directory
  *   skill://{skillName}/{path}  -> File within skill directory (template)
  */
 import * as fs from "node:fs";
@@ -49,39 +48,87 @@ function getMimeType(filePath) {
  * @param skillState - Shared state object (allows dynamic updates)
  */
 export function registerSkillResources(server, skillState) {
-    // Register collection resource for all skills
-    registerAllSkillsCollection(server, skillState);
     // Register template for individual skill SKILL.md files
     registerSkillTemplate(server, skillState);
+    // Register collection resource for skill directories (must be before file template)
+    registerSkillDirectoryCollection(server, skillState);
     // Register resource template for skill files
     registerSkillFileTemplate(server, skillState);
 }
 /**
- * Register a collection resource that returns all skills at once.
+ * Register a collection resource for skill directories.
  *
- * URI: skill://
+ * URI Pattern: skill://{skillName}/
  *
- * Returns multiple ResourceContents, one per skill, each with its own URI.
- * This allows clients to fetch all skill content in a single request.
+ * Returns all files in the skill directory (excluding SKILL.md) in a single request.
+ * This allows clients to fetch all resource files for a skill at once.
  */
-function registerAllSkillsCollection(server, skillState) {
-    server.registerResource("All Skills", "skill://", {
-        mimeType: "text/markdown",
-        description: "Collection of all available skills. Returns all SKILL.md contents in one request.",
-    }, async () => {
+function registerSkillDirectoryCollection(server, skillState) {
+    server.registerResource("Skill Directory", new ResourceTemplate("skill://{skillName}/", {
+        list: async () => {
+            // Return one entry per skill (the directory collection)
+            const resources = [];
+            for (const [name, skill] of skillState.skillMap) {
+                resources.push({
+                    uri: `skill://${encodeURIComponent(name)}/`,
+                    name: `${name}/`,
+                    mimeType: "text/plain",
+                    description: `All files in ${name} skill directory`,
+                });
+            }
+            return { resources };
+        },
+        complete: {
+            skillName: (value) => {
+                const names = Array.from(skillState.skillMap.keys());
+                return names.filter((n) => n.toLowerCase().startsWith(value.toLowerCase()));
+            },
+        },
+    }), {
+        mimeType: "text/plain",
+        description: "Collection of all files in a skill directory (excluding SKILL.md)",
+    }, async (resourceUri) => {
+        // Extract skill name from URI
+        const uriStr = resourceUri.toString();
+        const match = uriStr.match(/^skill:\/\/([^/]+)\/$/);
+        if (!match) {
+            throw new Error(`Invalid skill directory URI: ${uriStr}`);
+        }
+        const skillName = decodeURIComponent(match[1]);
+        const skill = skillState.skillMap.get(skillName);
+        if (!skill) {
+            const available = Array.from(skillState.skillMap.keys()).join(", ");
+            throw new Error(`Skill "${skillName}" not found. Available: ${available || "none"}`);
+        }
+        const skillDir = path.dirname(skill.path);
+        const files = listSkillFiles(skillDir);
         const contents = [];
-        for (const [name, skill] of skillState.skillMap) {
+        for (const file of files) {
+            const fullPath = path.join(skillDir, file);
+            // Security: Validate path is within skill directory
+            if (!isPathWithinBase(fullPath, skillDir)) {
+                continue; // Skip files outside skill directory
+            }
             try {
-                const content = loadSkillContent(skill.path);
+                const stat = fs.statSync(fullPath);
+                // Skip symlinks and directories
+                if (stat.isSymbolicLink() || stat.isDirectory()) {
+                    continue;
+                }
+                // Check file size
+                if (stat.size > MAX_FILE_SIZE) {
+                    continue; // Skip large files
+                }
+                const content = fs.readFileSync(fullPath, "utf-8");
                 contents.push({
-                    uri: `skill://${encodeURIComponent(name)}`,
-                    mimeType: "text/markdown",
+                    uri: `skill://${encodeURIComponent(skillName)}/${file}`,
+                    mimeType: getMimeType(file),
                     text: content,
                 });
             }
             catch (error) {
-                // Skip skills that fail to load, but continue with others
-                console.error(`Failed to load skill "${name}":`, error);
+                // Skip files that fail to load
+                console.error(`Failed to load file "${file}" in skill "${skillName}":`, error);
             }
         }
         return { contents };

package/dist/skill-tool.d.ts

@@ -7,7 +7,7 @@
  * Tools reference a shared SkillState object to support dynamic skill updates
  * when MCP roots change.
  */
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { McpServer, RegisteredTool } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { SkillMetadata } from "./skill-discovery.js";
 /**
  * Shared state for dynamic skill management.
@@ -15,15 +15,23 @@ import { SkillMetadata } from "./skill-discovery.js";
  */
 export interface SkillState {
     skillMap: Map<string, SkillMetadata>;
-    instructions: string;
 }
 /**
  * Register the "skill" tool with the MCP server.
  *
+ * The tool description includes the full skill discovery instructions (same format as
+ * server instructions) to enable dynamic updates via tools/listChanged notifications.
+ *
  * @param server - The McpServer instance
  * @param skillState - Shared state object (allows dynamic updates)
+ * @returns The registered tool, which can be updated when skills change
+ */
+/**
+ * Generate the full tool description including usage guidance and skill list.
+ * Exported so index.ts can use it when refreshing skills.
  */
-export declare function registerSkillTool(server: McpServer, skillState: SkillState): void;
+export declare function getToolDescription(skillState: SkillState): string;
+export declare function registerSkillTool(server: McpServer, skillState: SkillState): RegisteredTool;
 export declare const MAX_FILE_SIZE: number;
 export declare const MAX_DIRECTORY_DEPTH = 10;
 /**

package/dist/skill-tool.js

@@ -10,7 +10,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { z } from "zod";
-import { loadSkillContent } from "./skill-discovery.js";
+import { loadSkillContent, generateInstructions } from "./skill-discovery.js";
 /**
  * Input schema for the skill tool.
  */
@@ -20,14 +20,27 @@ const SkillSchema = z.object({
 /**
  * Register the "skill" tool with the MCP server.
  *
+ * The tool description includes the full skill discovery instructions (same format as
+ * server instructions) to enable dynamic updates via tools/listChanged notifications.
+ *
  * @param server - The McpServer instance
  * @param skillState - Shared state object (allows dynamic updates)
+ * @returns The registered tool, which can be updated when skills change
+ */
+/**
+ * Generate the full tool description including usage guidance and skill list.
+ * Exported so index.ts can use it when refreshing skills.
  */
+export function getToolDescription(skillState) {
+    const usage = "Load a skill's full instructions. Returns the complete SKILL.md content " +
+        "with step-by-step guidance, examples, and file references to follow.\n\n";
+    const skills = Array.from(skillState.skillMap.values());
+    return usage + generateInstructions(skills);
+}
 export function registerSkillTool(server, skillState) {
-    server.registerTool("skill", {
+    const skillTool = server.registerTool("skill", {
         title: "Activate Skill",
-        description: "Load a skill's full instructions. Returns the complete SKILL.md content " +
-            "with step-by-step guidance, examples, and file references to follow.",
+        description: getToolDescription(skillState),
         inputSchema: SkillSchema,
         annotations: {
             readOnlyHint: true,
@@ -76,6 +89,7 @@ export function registerSkillTool(server, skillState) {
     });
     // Register the skill-resource tool
     registerSkillResourceTool(server, skillState);
+    return skillTool;
 }
 /**
  * Input schema for the skill-resource tool.
@@ -90,7 +104,9 @@ const SkillResourceSchema = z.object({
         .describe("Relative path to file or directory. Examples: 'snippets/tool.ts' (single file), 'templates' (all files in directory), '' (list available files)."),
 });
 // Security constants (exported for reuse in skill-resources.ts)
-export const MAX_FILE_SIZE = 10 * 1024 * 1024; // 10MB max file size
+const DEFAULT_MAX_FILE_SIZE_MB = 1;
+const maxFileSizeMB = parseInt(process.env.MAX_FILE_SIZE_MB || "", 10) || DEFAULT_MAX_FILE_SIZE_MB;
+export const MAX_FILE_SIZE = maxFileSizeMB * 1024 * 1024; // Configurable via MAX_FILE_SIZE_MB env var
 export const MAX_DIRECTORY_DEPTH = 10; // Prevent deeply nested traversal
 /**
  * Check if a path is within the allowed base directory.

package/dist/subscriptions.d.ts

@@ -8,6 +8,7 @@
  * URI patterns supported:
  * - skill://              → Watch all skill directories
  * - skill://{name}        → Watch that skill's SKILL.md
+ * - skill://{name}/       → Watch entire skill directory (directory collection)
  * - skill://{name}/{path} → Watch specific file
  */
 import { FSWatcher } from "chokidar";

package/dist/subscriptions.js

@@ -8,6 +8,7 @@
  * URI patterns supported:
  * - skill://              → Watch all skill directories
  * - skill://{name}        → Watch that skill's SKILL.md
+ * - skill://{name}/       → Watch entire skill directory (directory collection)
  * - skill://{name}/{path} → Watch specific file
  */
 import chokidar from "chokidar";
@@ -50,6 +51,13 @@ export function resolveUriToFilePaths(uri, skillState) {
         const skill = skillState.skillMap.get(skillName);
         return skill ? [skill.path] : [];
     }
+    // skill://{skillName}/ → Watch entire skill directory (directory collection)
+    const dirMatch = uri.match(/^skill:\/\/([^/]+)\/$/);
+    if (dirMatch) {
+        const skillName = decodeURIComponent(dirMatch[1]);
+        const skill = skillState.skillMap.get(skillName);
+        return skill ? [path.dirname(skill.path)] : [];
+    }
     // skill://{skillName}/{path} → Specific file
     const fileMatch = uri.match(/^skill:\/\/([^/]+)\/(.+)$/);
     if (fileMatch) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olaservo/skill-jack-mcp",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "MCP server that discovers and serves Agent Skills. I know kung fu.",
   "type": "module",
   "main": "dist/index.js",