@olaservo/skill-jack-mcp 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,8 @@
 # Skill Jack MCP
 
-An MCP server that jacks [Agent Skills](https://agentskills.dev) directly into your LLM's brain.
+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.
 
 ## Features
 
@@ -33,17 +35,22 @@ npm run build
 
 ## Usage
 
-Configure a skills directory containing your Agent Skills:
+Configure one or more skills directories containing your Agent Skills:
 
 ```bash
-# Pass skills directory as argument
+# Single directory
 skill-jack-mcp /path/to/skills
 
-# Or use environment variable
+# Multiple directories (separate args or comma-separated)
+skill-jack-mcp /path/to/skills /path/to/more/skills
+skill-jack-mcp /path/to/skills,/path/to/more/skills
+
+# Using environment variable (comma-separated for multiple)
 SKILLS_DIR=/path/to/skills skill-jack-mcp
+SKILLS_DIR=/path/to/skills,/path/to/more/skills skill-jack-mcp
 ```
 
-The server scans the directory and its `.claude/skills/` and `skills/` subdirectories for skills.
+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
@@ -52,16 +59,16 @@ skill-jack-mcp "C:/Users/you/skills"
 
 ## How It Works
 
-The server implements the [Agent Skills](https://agentskills.dev) progressive disclosure pattern:
+The server implements the [Agent Skills](https://agentskills.io) progressive disclosure pattern:
 
-1. **At startup**: Discovers skills from configured directory
+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
 
 ```
 ┌─────────────────────────────────────────────────────────┐
 │ Server starts                                            │
-│   • Discovers skills from configured directory           │
+│   • Discovers skills from configured directories         │
 │   • Generates instructions with skill metadata           │
 │   ↓                                                      │
 │ MCP Client connects                                      │
@@ -96,7 +103,7 @@ Read files within a skill's directory (`scripts/`, `references/`, `assets/`, `sn
 
 This follows the Agent Skills spec's progressive disclosure pattern - resources are loaded only when needed.
 
-**Input:**
+**Read a single file:**
 ```json
 {
   "skill": "mcp-server-ts",
@@ -104,7 +111,14 @@ This follows the Agent Skills spec's progressive disclosure pattern - resources
 }
 ```
 
-**Output:** File content.
+**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
@@ -194,7 +208,7 @@ These are loaded into the model's system prompt by [clients](https://modelcontex
 
 ## Skill Discovery
 
-Skills are discovered at startup from the configured directory. The server checks:
+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
@@ -213,6 +227,6 @@ npx @modelcontextprotocol/inspector@latest node dist/index.js /path/to/skills
 
 ## Related
 
-- [Agent Skills Specification](https://agentskills.dev)
+- [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

@@ -6,7 +6,8 @@
  * Provides global skills with tools for progressive disclosure.
  *
  * Usage:
- *   skill-jack-mcp /path/to/skills    # Skills directory (required)
- *   SKILLS_DIR=/path/to/skills skill-jack-mcp
+ *   skill-jack-mcp /path/to/skills [/path2 ...]   # One or more directories
+ *   SKILLS_DIR=/path/to/skills skill-jack-mcp    # Single directory via env
+ *   SKILLS_DIR=/path1,/path2 skill-jack-mcp      # Multiple (comma-separated)
  */
 export {};

package/dist/index.js

@@ -6,8 +6,9 @@
  * Provides global skills with tools for progressive disclosure.
  *
  * Usage:
- *   skill-jack-mcp /path/to/skills    # Skills directory (required)
- *   SKILLS_DIR=/path/to/skills skill-jack-mcp
+ *   skill-jack-mcp /path/to/skills [/path2 ...]   # One or more directories
+ *   SKILLS_DIR=/path/to/skills skill-jack-mcp    # Single directory via env
+ *   SKILLS_DIR=/path1,/path2 skill-jack-mcp      # Multiple (comma-separated)
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -22,20 +23,40 @@ import { createSubscriptionManager, registerSubscriptionHandlers, } from "./subs
  */
 const SKILL_SUBDIRS = [".claude/skills", "skills"];
 /**
- * Get the skills directory from command line args or environment.
+ * Separator for multiple paths in SKILLS_DIR environment variable.
+ * Comma works cross-platform (not valid in file paths on any OS).
  */
-function getSkillsDir() {
-    // Check command line argument first
+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);
-    if (args.length > 0 && args[0] && !args[0].startsWith("-")) {
-        return path.resolve(args[0]);
+    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);
+        }
     }
-    // Fall back to environment variable
+    // Also check environment variable (comma-separated supported)
     const envDir = process.env.SKILLS_DIR;
     if (envDir) {
-        return path.resolve(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);
     }
-    return null;
+    // Deduplicate by resolved path
+    return [...new Set(dirs)];
 }
 /**
  * Shared state for skill management.
@@ -46,20 +67,37 @@ const skillState = {
     instructions: "",
 };
 /**
- * Discover skills from configured directory.
- * Checks both the directory itself and standard subdirectories.
+ * Discover skills from multiple configured directories.
+ * Each directory is checked along with its standard subdirectories.
+ * Handles duplicate skill names by keeping first occurrence.
  */
-function discoverSkillsFromDir(skillsDir) {
+function discoverSkillsFromDirs(skillsDirs) {
     const allSkills = [];
-    // Check if the directory itself contains skills
-    const directSkills = discoverSkills(skillsDir);
-    allSkills.push(...directSkills);
-    // Also check standard subdirectories
-    for (const subdir of SKILL_SUBDIRS) {
-        const subPath = path.join(skillsDir, subdir);
-        if (fs.existsSync(subPath)) {
-            const subdirSkills = discoverSkills(subPath);
-            allSkills.push(...subdirSkills);
+    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;
@@ -69,16 +107,17 @@ function discoverSkillsFromDir(skillsDir) {
  */
 const subscriptionManager = createSubscriptionManager();
 async function main() {
-    const skillsDir = getSkillsDir();
-    if (!skillsDir) {
+    const skillsDirs = getSkillsDirs();
+    if (skillsDirs.length === 0) {
         console.error("No skills directory configured.");
-        console.error("Usage: skill-jack-mcp /path/to/skills");
+        console.error("Usage: skill-jack-mcp /path/to/skills [/path/to/more/skills ...]");
         console.error("   or: SKILLS_DIR=/path/to/skills skill-jack-mcp");
+        console.error("   or: SKILLS_DIR=/path1,/path2 skill-jack-mcp");
         process.exit(1);
     }
-    console.error(`Skills directory: ${skillsDir}`);
+    console.error(`Skills directories: ${skillsDirs.join(", ")}`);
     // Discover skills at startup
-    const skills = discoverSkillsFromDir(skillsDir);
+    const skills = discoverSkillsFromDirs(skillsDirs);
     skillState.skillMap = createSkillMap(skills);
     skillState.instructions = generateInstructions(skills);
     console.error(`Discovered ${skills.length} skill(s)`);

package/dist/skill-tool.js

@@ -87,7 +87,7 @@ 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."),
+        .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

package/package.json

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