@olaservo/skill-jack-mcp 0.1.0

package/dist/skill-tool.js

@@ -0,0 +1,346 @@
+/**
+ * MCP tool registration for skill-related tools.
+ *
+ * - skill: Load and activate a skill by name (returns SKILL.md content)
+ * - skill-resource: Read files within a skill directory (scripts/, references/, assets/, etc.)
+ *
+ * Tools reference a shared SkillState object to support dynamic skill updates
+ * when MCP roots change.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { z } from "zod";
+import { loadSkillContent } from "./skill-discovery.js";
+/**
+ * Input schema for the skill tool.
+ */
+const SkillSchema = z.object({
+    name: z.string().describe("Skill name from <available_skills>"),
+});
+/**
+ * Register the "skill" tool with the MCP server.
+ *
+ * @param server - The McpServer instance
+ * @param skillState - Shared state object (allows dynamic updates)
+ */
+export function registerSkillTool(server, skillState) {
+    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.",
+        inputSchema: SkillSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async (args) => {
+        const { name } = SkillSchema.parse(args);
+        const skill = skillState.skillMap.get(name);
+        if (!skill) {
+            const availableSkills = Array.from(skillState.skillMap.keys()).join(", ");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Skill "${name}" not found. Available skills: ${availableSkills || "none"}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        try {
+            const content = loadSkillContent(skill.path);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: content,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Failed to load skill "${name}": ${message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // Register the skill-resource tool
+    registerSkillResourceTool(server, skillState);
+}
+/**
+ * Input schema for the skill-resource tool.
+ *
+ * Per the Agent Skills spec, file references use relative paths from the skill root.
+ * Common directories: scripts/, references/, assets/
+ */
+const SkillResourceSchema = z.object({
+    skill: z.string().describe("Skill name"),
+    path: z
+        .string()
+        .describe("Relative path (e.g., 'snippets/tool.ts'). Empty string lists all files."),
+});
+// Security constants (exported for reuse in skill-resources.ts)
+export const MAX_FILE_SIZE = 10 * 1024 * 1024; // 10MB max file size
+export const MAX_DIRECTORY_DEPTH = 10; // Prevent deeply nested traversal
+/**
+ * Check if a path is within the allowed base directory.
+ * Uses fs.realpathSync to resolve symlinks and prevent symlink escape attacks.
+ */
+export function isPathWithinBase(targetPath, baseDir) {
+    try {
+        // Resolve symlinks to get the real paths
+        const realBase = fs.realpathSync(baseDir);
+        const realTarget = fs.realpathSync(targetPath);
+        const normalizedBase = realBase + path.sep;
+        return realTarget === realBase || realTarget.startsWith(normalizedBase);
+    }
+    catch {
+        // If realpathSync fails (e.g., file doesn't exist), fall back to resolve check
+        // This is safe because we'll get an error when trying to read anyway
+        const normalizedBase = path.resolve(baseDir) + path.sep;
+        const normalizedPath = path.resolve(targetPath);
+        return normalizedPath.startsWith(normalizedBase);
+    }
+}
+/**
+ * List files in a skill directory for discovery.
+ * Limits recursion depth to prevent DoS from deeply nested directories.
+ */
+export function listSkillFiles(skillDir, subPath = "", depth = 0) {
+    // Prevent excessive recursion
+    if (depth > MAX_DIRECTORY_DEPTH) {
+        return [];
+    }
+    const files = [];
+    const dirPath = path.join(skillDir, subPath);
+    if (!fs.existsSync(dirPath) || !fs.statSync(dirPath).isDirectory()) {
+        return files;
+    }
+    const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+    for (const entry of entries) {
+        const relativePath = path.join(subPath, entry.name);
+        // Skip symlinks to prevent escape and infinite loops
+        if (entry.isSymbolicLink()) {
+            continue;
+        }
+        if (entry.isDirectory()) {
+            // Skip node_modules and hidden directories
+            if (entry.name !== "node_modules" && !entry.name.startsWith(".")) {
+                files.push(...listSkillFiles(skillDir, relativePath, depth + 1));
+            }
+        }
+        else {
+            // Skip SKILL.md (use skill tool for that) and common non-resource files
+            if (entry.name !== "SKILL.md" && entry.name !== "skill.md") {
+                files.push(relativePath.replace(/\\/g, "/"));
+            }
+        }
+    }
+    return files;
+}
+/**
+ * Register the "skill-resource" tool with the MCP server.
+ *
+ * This tool provides access to files within a skill's directory structure,
+ * following the Agent Skills spec for progressive disclosure of resources.
+ *
+ * @param server - The McpServer instance
+ * @param skillState - Shared state object (allows dynamic updates)
+ */
+function registerSkillResourceTool(server, skillState) {
+    server.registerTool("skill-resource", {
+        title: "Read Skill File",
+        description: "Read files referenced by skill instructions (scripts, snippets, templates). " +
+            "Use when skill instructions mention specific files to read or copy. " +
+            "Pass a directory path (e.g., 'templates') to read all files in that directory at once.",
+        inputSchema: SkillResourceSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async (args) => {
+        const { skill: skillName, path: resourcePath } = SkillResourceSchema.parse(args);
+        const skill = skillState.skillMap.get(skillName);
+        if (!skill) {
+            const availableSkills = Array.from(skillState.skillMap.keys()).join(", ");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Skill "${skillName}" not found. Available skills: ${availableSkills || "none"}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        // Get the skill directory (parent of SKILL.md)
+        const skillDir = path.dirname(skill.path);
+        // If path is empty, list available files
+        if (!resourcePath || resourcePath.trim() === "") {
+            const files = listSkillFiles(skillDir);
+            if (files.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `No resource files found in skill "${skillName}". The skill only contains SKILL.md.`,
+                        },
+                    ],
+                };
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Available resources in skill "${skillName}":\n\n${files.map((f) => `- ${f}`).join("\n")}`,
+                    },
+                ],
+            };
+        }
+        // Resolve the full path and validate it's within the skill directory
+        const fullPath = path.resolve(skillDir, resourcePath);
+        if (!isPathWithinBase(fullPath, skillDir)) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Invalid path: "${resourcePath}" is outside the skill directory. Use relative paths like "scripts/example.py" or "references/guide.md".`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        // Check if file exists
+        if (!fs.existsSync(fullPath)) {
+            const files = listSkillFiles(skillDir);
+            const suggestions = files.slice(0, 10).join("\n- ");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Resource "${resourcePath}" not found in skill "${skillName}".\n\nAvailable files:\n- ${suggestions}${files.length > 10 ? `\n... and ${files.length - 10} more` : ""}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        // Check file stats
+        const stat = fs.statSync(fullPath);
+        // Reject symlinks that point outside (defense in depth)
+        if (stat.isSymbolicLink()) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Cannot read symlink "${resourcePath}". Only regular files within the skill directory are accessible.`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        // Handle directories - return all file contents
+        if (stat.isDirectory()) {
+            const files = listSkillFiles(skillDir, resourcePath);
+            if (files.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Directory "${resourcePath}" is empty or contains no readable files.`,
+                        },
+                    ],
+                };
+            }
+            // Read all files and return as multiple content items
+            const contents = [];
+            for (const file of files) {
+                const filePath = path.join(skillDir, file);
+                try {
+                    const fileStat = fs.statSync(filePath);
+                    if (fileStat.size > MAX_FILE_SIZE) {
+                        contents.push({
+                            type: "text",
+                            text: `--- ${file} ---\n[File too large: ${(fileStat.size / 1024 / 1024).toFixed(2)}MB]`,
+                        });
+                    }
+                    else {
+                        const fileContent = fs.readFileSync(filePath, "utf-8");
+                        contents.push({
+                            type: "text",
+                            text: `--- ${file} ---\n${fileContent}`,
+                        });
+                    }
+                }
+                catch (error) {
+                    contents.push({
+                        type: "text",
+                        text: `--- ${file} ---\n[Error reading file: ${error instanceof Error ? error.message : "unknown error"}]`,
+                    });
+                }
+            }
+            return { content: contents };
+        }
+        // Check file size to prevent memory exhaustion
+        if (stat.size > MAX_FILE_SIZE) {
+            const sizeMB = (stat.size / 1024 / 1024).toFixed(2);
+            const maxMB = (MAX_FILE_SIZE / 1024 / 1024).toFixed(0);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `File "${resourcePath}" is too large (${sizeMB}MB). Maximum allowed size is ${maxMB}MB.`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        // Final symlink check using realpath (defense in depth)
+        if (!isPathWithinBase(fullPath, skillDir)) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Access denied: "${resourcePath}" resolves to a location outside the skill directory.`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        // Read and return the file content
+        try {
+            const content = fs.readFileSync(fullPath, "utf-8");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: content,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Failed to read resource "${resourcePath}": ${message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/subscriptions.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Resource subscription management with file watching.
+ *
+ * Tracks client subscriptions to resource URIs and watches underlying files
+ * using chokidar. When files change, sends notifications/resources/updated
+ * to subscribed clients.
+ *
+ * URI patterns supported:
+ * - skill://              → Watch all skill directories
+ * - skill://{name}        → Watch that skill's SKILL.md
+ * - skill://{name}/{path} → Watch specific file
+ */
+import { FSWatcher } from "chokidar";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { SkillState } from "./skill-tool.js";
+/**
+ * Manages active subscriptions and their associated file watchers.
+ */
+export interface SubscriptionManager {
+    /** URI -> Set of file paths being watched for this URI */
+    uriToFilePaths: Map<string, Set<string>>;
+    /** File path -> Set of URIs that depend on this file */
+    filePathToUris: Map<string, Set<string>>;
+    /** File path -> chokidar watcher instance */
+    watchers: Map<string, FSWatcher>;
+    /** Pending notification timeouts for debouncing (URI -> timeout) */
+    pendingNotifications: Map<string, NodeJS.Timeout>;
+}
+/**
+ * Create a new subscription manager.
+ */
+export declare function createSubscriptionManager(): SubscriptionManager;
+/**
+ * Resolve a skill:// URI to the file paths it depends on.
+ *
+ * @param uri - The resource URI
+ * @param skillState - Current skill state for lookups
+ * @returns Array of absolute file paths to watch
+ */
+export declare function resolveUriToFilePaths(uri: string, skillState: SkillState): string[];
+/**
+ * Add a subscription for a URI.
+ *
+ * @param manager - The subscription manager
+ * @param uri - The resource URI to subscribe to
+ * @param skillState - Current skill state for resolving URIs
+ * @param onNotify - Callback to send notification when file changes
+ * @returns True if subscription was added, false if URI couldn't be resolved
+ */
+export declare function subscribe(manager: SubscriptionManager, uri: string, skillState: SkillState, onNotify: (uri: string) => void): boolean;
+/**
+ * Remove a subscription for a URI.
+ *
+ * @param manager - The subscription manager
+ * @param uri - The resource URI to unsubscribe from
+ */
+export declare function unsubscribe(manager: SubscriptionManager, uri: string): void;
+/**
+ * Update subscriptions when skills change.
+ *
+ * Re-resolves all existing URIs with the new skill state and updates
+ * watchers accordingly. Sends notifications for any URIs whose underlying
+ * files have changed.
+ *
+ * @param manager - The subscription manager
+ * @param skillState - Updated skill state
+ * @param onNotify - Callback to send notification
+ */
+export declare function refreshSubscriptions(manager: SubscriptionManager, skillState: SkillState, onNotify: (uri: string) => void): void;
+/**
+ * Register subscribe/unsubscribe request handlers with the server.
+ *
+ * @param server - The MCP server instance
+ * @param skillState - Shared skill state
+ * @param manager - The subscription manager
+ */
+export declare function registerSubscriptionHandlers(server: McpServer, skillState: SkillState, manager: SubscriptionManager): void;

package/dist/subscriptions.js

@@ -0,0 +1,277 @@
+/**
+ * Resource subscription management with file watching.
+ *
+ * Tracks client subscriptions to resource URIs and watches underlying files
+ * using chokidar. When files change, sends notifications/resources/updated
+ * to subscribed clients.
+ *
+ * URI patterns supported:
+ * - skill://              → Watch all skill directories
+ * - skill://{name}        → Watch that skill's SKILL.md
+ * - skill://{name}/{path} → Watch specific file
+ */
+import chokidar from "chokidar";
+import * as path from "node:path";
+import { SubscribeRequestSchema, UnsubscribeRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { isPathWithinBase } from "./skill-tool.js";
+/** Debounce delay in milliseconds */
+const DEBOUNCE_MS = 100;
+/**
+ * Create a new subscription manager.
+ */
+export function createSubscriptionManager() {
+    return {
+        uriToFilePaths: new Map(),
+        filePathToUris: new Map(),
+        watchers: new Map(),
+        pendingNotifications: new Map(),
+    };
+}
+/**
+ * Resolve a skill:// URI to the file paths it depends on.
+ *
+ * @param uri - The resource URI
+ * @param skillState - Current skill state for lookups
+ * @returns Array of absolute file paths to watch
+ */
+export function resolveUriToFilePaths(uri, skillState) {
+    // skill:// → Watch all skill directories
+    if (uri === "skill://") {
+        const paths = [];
+        for (const skill of skillState.skillMap.values()) {
+            paths.push(path.dirname(skill.path)); // Watch entire skill directory
+        }
+        return paths;
+    }
+    // skill://{skillName} → Just the SKILL.md file
+    const skillMatch = uri.match(/^skill:\/\/([^/]+)$/);
+    if (skillMatch) {
+        const skillName = decodeURIComponent(skillMatch[1]);
+        const skill = skillState.skillMap.get(skillName);
+        return skill ? [skill.path] : [];
+    }
+    // skill://{skillName}/{path} → Specific file
+    const fileMatch = uri.match(/^skill:\/\/([^/]+)\/(.+)$/);
+    if (fileMatch) {
+        const skillName = decodeURIComponent(fileMatch[1]);
+        const filePath = fileMatch[2];
+        const skill = skillState.skillMap.get(skillName);
+        if (!skill)
+            return [];
+        const skillDir = path.dirname(skill.path);
+        const fullPath = path.resolve(skillDir, filePath);
+        // Security check: ensure path is within skill directory
+        if (!isPathWithinBase(fullPath, skillDir))
+            return [];
+        return [fullPath];
+    }
+    return [];
+}
+/**
+ * Add a subscription for a URI.
+ *
+ * @param manager - The subscription manager
+ * @param uri - The resource URI to subscribe to
+ * @param skillState - Current skill state for resolving URIs
+ * @param onNotify - Callback to send notification when file changes
+ * @returns True if subscription was added, false if URI couldn't be resolved
+ */
+export function subscribe(manager, uri, skillState, onNotify) {
+    const filePaths = resolveUriToFilePaths(uri, skillState);
+    if (filePaths.length === 0) {
+        return false;
+    }
+    // Track URI -> file paths mapping
+    manager.uriToFilePaths.set(uri, new Set(filePaths));
+    // Track reverse mapping and set up watchers
+    for (const filePath of filePaths) {
+        // Add to reverse mapping
+        let uris = manager.filePathToUris.get(filePath);
+        if (!uris) {
+            uris = new Set();
+            manager.filePathToUris.set(filePath, uris);
+        }
+        uris.add(uri);
+        // Set up watcher if not already watching this path
+        if (!manager.watchers.has(filePath)) {
+            const watcher = createWatcher(filePath, manager, onNotify);
+            manager.watchers.set(filePath, watcher);
+        }
+    }
+    console.error(`Subscribed to ${uri} (watching ${filePaths.length} path(s))`);
+    return true;
+}
+/**
+ * Remove a subscription for a URI.
+ *
+ * @param manager - The subscription manager
+ * @param uri - The resource URI to unsubscribe from
+ */
+export function unsubscribe(manager, uri) {
+    const filePaths = manager.uriToFilePaths.get(uri);
+    if (!filePaths) {
+        return;
+    }
+    // Remove URI from each file path's set
+    for (const filePath of filePaths) {
+        const uris = manager.filePathToUris.get(filePath);
+        if (uris) {
+            uris.delete(uri);
+            // If no more URIs depend on this file, stop watching
+            if (uris.size === 0) {
+                manager.filePathToUris.delete(filePath);
+                const watcher = manager.watchers.get(filePath);
+                if (watcher) {
+                    watcher.close();
+                    manager.watchers.delete(filePath);
+                }
+            }
+        }
+    }
+    // Remove the URI entry
+    manager.uriToFilePaths.delete(uri);
+    // Clear any pending notification
+    const pending = manager.pendingNotifications.get(uri);
+    if (pending) {
+        clearTimeout(pending);
+        manager.pendingNotifications.delete(uri);
+    }
+    console.error(`Unsubscribed from ${uri}`);
+}
+/**
+ * Create a chokidar watcher for a file or directory.
+ */
+function createWatcher(filePath, manager, onNotify) {
+    const watcher = chokidar.watch(filePath, {
+        persistent: true,
+        ignoreInitial: true,
+        awaitWriteFinish: {
+            stabilityThreshold: DEBOUNCE_MS,
+            pollInterval: 50,
+        },
+    });
+    const handleChange = (changedPath) => {
+        // Normalize path for consistent lookup
+        const normalizedPath = path.normalize(changedPath);
+        // Find all URIs affected by this file change
+        // For directory watches, check if the changed file is within any watched directory
+        for (const [watchedPath, uris] of manager.filePathToUris.entries()) {
+            const isMatch = normalizedPath === watchedPath ||
+                normalizedPath.startsWith(watchedPath + path.sep);
+            if (isMatch) {
+                for (const uri of uris) {
+                    // Debounce: clear existing timeout, set new one
+                    const existing = manager.pendingNotifications.get(uri);
+                    if (existing) {
+                        clearTimeout(existing);
+                    }
+                    manager.pendingNotifications.set(uri, setTimeout(() => {
+                        manager.pendingNotifications.delete(uri);
+                        console.error(`Resource updated: ${uri}`);
+                        onNotify(uri);
+                    }, DEBOUNCE_MS));
+                }
+            }
+        }
+    };
+    watcher.on("change", handleChange);
+    watcher.on("add", handleChange);
+    watcher.on("unlink", handleChange);
+    return watcher;
+}
+/**
+ * Update subscriptions when skills change.
+ *
+ * Re-resolves all existing URIs with the new skill state and updates
+ * watchers accordingly. Sends notifications for any URIs whose underlying
+ * files have changed.
+ *
+ * @param manager - The subscription manager
+ * @param skillState - Updated skill state
+ * @param onNotify - Callback to send notification
+ */
+export function refreshSubscriptions(manager, skillState, onNotify) {
+    // Re-resolve each subscribed URI
+    for (const uri of manager.uriToFilePaths.keys()) {
+        const oldPaths = manager.uriToFilePaths.get(uri);
+        const newPaths = new Set(resolveUriToFilePaths(uri, skillState));
+        // Find paths that were removed
+        for (const oldPath of oldPaths) {
+            if (!newPaths.has(oldPath)) {
+                // Remove this URI from the old path's set
+                const uris = manager.filePathToUris.get(oldPath);
+                if (uris) {
+                    uris.delete(uri);
+                    if (uris.size === 0) {
+                        manager.filePathToUris.delete(oldPath);
+                        const watcher = manager.watchers.get(oldPath);
+                        if (watcher) {
+                            watcher.close();
+                            manager.watchers.delete(oldPath);
+                        }
+                    }
+                }
+            }
+        }
+        // Find paths that were added
+        for (const newPath of newPaths) {
+            if (!oldPaths.has(newPath)) {
+                // Add this URI to the new path's set
+                let uris = manager.filePathToUris.get(newPath);
+                if (!uris) {
+                    uris = new Set();
+                    manager.filePathToUris.set(newPath, uris);
+                }
+                uris.add(uri);
+                // Start watching if not already
+                if (!manager.watchers.has(newPath)) {
+                    const watcher = createWatcher(newPath, manager, onNotify);
+                    manager.watchers.set(newPath, watcher);
+                }
+            }
+        }
+        // Update the stored paths
+        if (newPaths.size === 0) {
+            // URI no longer resolves to anything - remove subscription
+            manager.uriToFilePaths.delete(uri);
+            console.error(`Subscription ${uri} no longer valid (skill removed?)`);
+        }
+        else {
+            manager.uriToFilePaths.set(uri, newPaths);
+        }
+    }
+}
+/**
+ * Register subscribe/unsubscribe request handlers with the server.
+ *
+ * @param server - The MCP server instance
+ * @param skillState - Shared skill state
+ * @param manager - The subscription manager
+ */
+export function registerSubscriptionHandlers(server, skillState, manager) {
+    const sendNotification = (uri) => {
+        server.server.notification({
+            method: "notifications/resources/updated",
+            params: { uri },
+        });
+    };
+    // Handle resources/subscribe requests
+    server.server.setRequestHandler(SubscribeRequestSchema, async (request) => {
+        const { uri } = request.params;
+        // Validate URI scheme
+        if (!uri.startsWith("skill://")) {
+            throw new Error(`Unsupported URI scheme: ${uri}. Only skill:// URIs are supported.`);
+        }
+        const success = subscribe(manager, uri, skillState, sendNotification);
+        if (!success) {
+            throw new Error(`Resource not found: ${uri}`);
+        }
+        return {};
+    });
+    // Handle resources/unsubscribe requests
+    server.server.setRequestHandler(UnsubscribeRequestSchema, async (request) => {
+        const { uri } = request.params;
+        unsubscribe(manager, uri);
+        return {};
+    });
+}