@skilljack/mcp 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ola Hungerford
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,260 @@
+# Skilljack MCP
+
+An MCP server that jacks [Agent Skills](https://agentskills.io) directly into your LLM's brain.
+
+> **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
+
+- **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`
+
+## Installation
+
+```bash
+npm install @skilljack/mcp
+```
+
+Or run directly with npx:
+
+```bash
+npx @skilljack/mcp /path/to/skills
+```
+
+### From Source
+
+```bash
+git clone https://github.com/olaservo/skilljack-mcp.git
+cd skilljack-mcp
+npm install
+npm run build
+```
+
+## Usage
+
+Configure one or more skills directories containing your Agent Skills:
+
+```bash
+# Single directory
+skilljack-mcp /path/to/skills
+
+# Multiple directories (separate args or comma-separated)
+skilljack-mcp /path/to/skills /path/to/more/skills
+skilljack-mcp /path/to/skills,/path/to/more/skills
+
+# Using environment variable (comma-separated for multiple)
+SKILLS_DIR=/path/to/skills skilljack-mcp
+SKILLS_DIR=/path/to/skills,/path/to/more/skills skilljack-mcp
+```
+
+Each directory is scanned along with its `.claude/skills/` and `skills/` subdirectories for skills. Duplicate skill names are handled by keeping the first occurrence.
+
+**Windows note**: Use forward slashes in paths when using with MCP Inspector:
+```bash
+skilljack-mcp "C:/Users/you/skills"
+```
+
+## How It Works
+
+The server implements the [Agent Skills](https://agentskills.io) progressive disclosure pattern with dynamic updates:
+
+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         │
+│   • Starts watching for SKILL.md changes                 │
+│   ↓                                                      │
+│ MCP Client connects                                      │
+│   • Skill tool description includes available skills     │
+│   ↓                                                      │
+│ 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.          │
+└─────────────────────────────────────────────────────────┘
+```
+
+## Tools vs Resources
+
+This server exposes skills via both **tools** and **resources**:
+
+- **Tools** (`skill`, `skill-resource`) - For your agent to use autonomously. The LLM sees available skills in the tool description and calls them as needed.
+- **Resources** (`skill://` URIs) - For manual selection in apps that support it (e.g., Claude Desktop's resource picker). Useful when you want to explicitly attach a skill to the conversation.
+
+Most users will rely on tools for automatic skill activation. Resources provide an alternative for manual control.
+
+## Tools
+
+### `skill`
+
+Load and activate an Agent Skill by name. Returns the full SKILL.md content.
+
+**Input:**
+```json
+{
+  "name": "skill-name"
+}
+```
+
+**Output:** Full SKILL.md content including frontmatter and instructions.
+
+### `skill-resource`
+
+Read files within a skill's directory (`scripts/`, `references/`, `assets/`, `snippets/`, etc.).
+
+This follows the Agent Skills spec's progressive disclosure pattern - resources are loaded only when needed.
+
+**Read a single file:**
+```json
+{
+  "skill": "mcp-server-ts",
+  "path": "snippets/tools/echo.ts"
+}
+```
+
+**Read all files in a directory:**
+```json
+{
+  "skill": "algorithmic-art",
+  "path": "templates"
+}
+```
+Returns all files in the directory as multiple content items.
+
+**List available files** (pass empty path):
+```json
+{
+  "skill": "mcp-server-ts",
+  "path": ""
+}
+```
+
+**Security:** Path traversal is prevented - only files within the skill directory can be accessed.
+
+## Resources
+
+Skills are also accessible via MCP [Resources](https://modelcontextprotocol.io/specification/2025-11-25/server/resources#resources) using `skill://` URIs.
+
+### URI Patterns
+
+| URI | Returns |
+|-----|---------|
+| `skill://{name}` | Single skill's SKILL.md content |
+| `skill://{name}/` | All files in skill directory (collection) |
+| `skill://{name}/{path}` | Specific file within skill |
+
+### Resource Subscriptions
+
+Clients can subscribe to resources for real-time updates when files change.
+
+**Capability:** `resources: { subscribe: true, listChanged: true }`
+
+**Subscribe to a resource:**
+```
+→ resources/subscribe { uri: "skill://mcp-server-ts" }
+← {} (success)
+```
+
+**Receive notifications when files change:**
+```
+← notifications/resources/updated { uri: "skill://mcp-server-ts" }
+```
+
+**Unsubscribe:**
+```
+→ resources/unsubscribe { uri: "skill://mcp-server-ts" }
+← {} (success)
+```
+
+**How it works:**
+1. Client subscribes to a `skill://` URI
+2. Server resolves URI to file path(s) and starts watching with chokidar
+3. When files change, server debounces (100ms) and sends notification
+4. Client can re-read the resource to get updated content
+
+## Security
+
+**Skills are treated as trusted content.** This server reads and serves skill files directly to clients without sanitization. Only configure skills directories containing content you trust.
+
+Protections in place:
+- Path traversal prevention (symlink-aware)
+- File size limits (1MB default, configurable via `MAX_FILE_SIZE_MB` env var)
+- Directory depth limits
+- Skill content is confined to configured directories
+
+Not protected against:
+- Malicious content within trusted skill directories
+- Prompt injection via skill instructions (skills can influence LLM behavior by design)
+
+## 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 `skill` tool description includes metadata for all available skills in XML format:
+
+```markdown
+# Skills
+
+When a user's task matches a skill description below: 1) activate it, 2) follow its instructions completely.
+
+<available_skills>
+<skill>
+<name>mcp-server-ts</name>
+<description>Build TypeScript MCP servers with composable code snippets...</description>
+<location>C:/path/to/mcp-server-ts/SKILL.md</location>
+</skill>
+</available_skills>
+```
+
+This metadata is dynamically updated when skills change - clients supporting `tools/listChanged` will automatically refresh.
+
+## Skill Discovery
+
+Skills are discovered at startup from the configured directories. For each directory, the server checks:
+- The directory itself for skill subdirectories
+- `.claude/skills/` subdirectory
+- `skills/` subdirectory
+
+Each skill subdirectory must contain a `SKILL.md` file with YAML frontmatter including `name` and `description` fields.
+
+## Testing
+
+```bash
+# Build first
+npm run build
+
+# Test with MCP Inspector
+npx @modelcontextprotocol/inspector@latest node dist/index.js /path/to/skills
+```
+
+## Related
+
+- [Agent Skills Specification](https://agentskills.io)
+- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
+- [Example MCP Clients](https://modelcontextprotocol.io/clients)

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * Skilljack MCP - "I know kung fu."
+ *
+ * MCP server that jacks Agent Skills directly into your LLM's brain.
+ * 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)
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,271 @@
+#!/usr/bin/env node
+/**
+ * Skilljack MCP - "I know kung fu."
+ *
+ * MCP server that jacks Agent Skills directly into your LLM's brain.
+ * 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)
+ */
+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 { registerSkillTool, getToolDescription } from "./skill-tool.js";
+import { registerSkillResources } from "./skill-resources.js";
+import { createSubscriptionManager, registerSubscriptionHandlers, refreshSubscriptions, } from "./subscriptions.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).
+ */
+const PATH_LIST_SEPARATOR = ",";
+/**
+ * Get the skills directories from command line args and/or environment.
+ * Returns deduplicated, resolved paths.
+ */
+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);
+        }
+    }
+    // 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);
+    }
+    // Deduplicate by resolved path
+    return [...new Set(dirs)];
+}
+/**
+ * Shared state for skill management.
+ * Tools and resources reference this state.
+ */
+const skillState = {
+    skillMap: new Map(),
+};
+/**
+ * Discover skills from multiple configured directories.
+ * Each directory is checked along with its standard subdirectories.
+ * Handles duplicate skill names by keeping first occurrence.
+ */
+function discoverSkillsFromDirs(skillsDirs) {
+    const allSkills = [];
+    const seenNames = new Map(); // name -> source directory
+    for (const skillsDir of skillsDirs) {
+        if (!fs.existsSync(skillsDir)) {
+            console.error(`Warning: Skills directory not found: ${skillsDir}`);
+            continue;
+        }
+        console.error(`Scanning skills directory: ${skillsDir}`);
+        // Check if the directory itself contains skills
+        const dirSkills = discoverSkills(skillsDir);
+        // Also check standard subdirectories
+        for (const subdir of SKILL_SUBDIRS) {
+            const subPath = path.join(skillsDir, subdir);
+            if (fs.existsSync(subPath)) {
+                dirSkills.push(...discoverSkills(subPath));
+            }
+        }
+        // Add skills, checking for duplicates
+        for (const skill of dirSkills) {
+            if (seenNames.has(skill.name)) {
+                console.error(`Warning: Duplicate skill "${skill.name}" found in ${path.dirname(skill.path)} ` +
+                    `(already loaded from ${seenNames.get(skill.name)})`);
+                continue; // Skip duplicate
+            }
+            seenNames.set(skill.name, path.dirname(skill.path));
+            allSkills.push(skill);
+        }
+    }
+    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.
+ */
+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);
+    }
+    console.error(`Skills directories: ${skillsDirs.join(", ")}`);
+    // Discover skills at startup
+    const skills = discoverSkillsFromDirs(skillsDirs);
+    skillState.skillMap = createSkillMap(skills);
+    console.error(`Discovered ${skills.length} skill(s)`);
+    // Create the MCP server
+    const server = new McpServer({
+        name: "skilljack-mcp",
+        version: "1.0.0",
+    }, {
+        capabilities: {
+            tools: { listChanged: true },
+            resources: { subscribe: true, listChanged: true },
+        },
+    });
+    // Register tools and resources
+    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);
+    console.error("Skilljack ready. I know kung fu.");
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/dist/roots-handler.d.ts

@@ -0,0 +1,49 @@
+/**
+ * MCP Roots handler for dynamic skill discovery.
+ *
+ * Requests roots from the client, scans for skills in each root,
+ * and handles root change notifications.
+ *
+ * Pattern adapted from:
+ * - .claude/skills/mcp-server-ts/snippets/server/index.ts (oninitialized, syncRoots)
+ * - .claude/skills/mcp-client-ts/snippets/handlers/roots.ts (URI conversion)
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { SkillMetadata } from "./skill-discovery.js";
+/**
+ * Skill discovery locations within each root.
+ */
+export declare const SKILL_SUBDIRS: string[];
+/**
+ * Discover skills from all roots provided by the client.
+ *
+ * Scans each root for skill directories (.claude/skills/, skills/)
+ * and handles naming conflicts by prefixing with root name.
+ *
+ * @param roots - Array of Root objects from client's roots/list response
+ * @returns Object containing discovered skills
+ */
+export declare function discoverSkillsFromRoots(roots: Array<{
+    uri: string;
+    name?: string;
+}>): {
+    skills: SkillMetadata[];
+    rootSources: Map<string, string>;
+};
+/**
+ * Callback type for when skills are updated.
+ */
+export type SkillsChangedCallback = (skillMap: Map<string, SkillMetadata>, instructions: string) => void;
+/**
+ * Sync skills from roots or configured skills directory.
+ *
+ * Pattern from mcp-server-ts snippets/server/index.ts:
+ * - Check client capabilities
+ * - Request roots if supported
+ * - Use skills directory if not
+ *
+ * @param server - The McpServer instance
+ * @param skillsDir - Optional skills directory if client doesn't support roots
+ * @param onSkillsChanged - Callback when skills are updated
+ */
+export declare function syncSkills(server: McpServer, skillsDir: string | null, onSkillsChanged: SkillsChangedCallback): Promise<void>;