@olaservo/skill-jack-mcp 0.1.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,218 @@
+# Skill Jack MCP
+
+An MCP server that jacks [Agent Skills](https://agentskills.dev) directly into your LLM's brain.
+
+## Features
+
+- **Skill Discovery** - Discovers skills from a configured directory at startup
+- **Server Instructions** - Injects skill metadata into the system prompt (for clients supporting instructions)
+- **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 @olaservo/skill-jack-mcp
+```
+
+Or run directly with npx:
+
+```bash
+npx @olaservo/skill-jack-mcp /path/to/skills
+```
+
+### From Source
+
+```bash
+git clone https://github.com/olaservo/skill-jack-mcp.git
+cd skill-jack-mcp
+npm install
+npm run build
+```
+
+## Usage
+
+Configure a skills directory containing your Agent Skills:
+
+```bash
+# Pass skills directory as argument
+skill-jack-mcp /path/to/skills
+
+# Or use environment variable
+SKILLS_DIR=/path/to/skills skill-jack-mcp
+```
+
+The server scans the directory and its `.claude/skills/` and `skills/` subdirectories for skills.
+
+**Windows note**: Use forward slashes in paths when using with MCP Inspector:
+```bash
+skill-jack-mcp "C:/Users/you/skills"
+```
+
+## How It Works
+
+The server implements the [Agent Skills](https://agentskills.dev) progressive disclosure pattern:
+
+1. **At startup**: Discovers skills from configured directory
+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           │
+│   • Generates instructions with skill metadata           │
+│   ↓                                                      │
+│ MCP Client connects                                      │
+│   • Server instructions included in initialize response  │
+│   ↓                                                      │
+│ LLM sees skill metadata in system prompt                 │
+│   ↓                                                      │
+│ LLM calls "skill" tool with skill name                   │
+│   ↓                                                      │
+│ Server returns full SKILL.md content                     │
+└─────────────────────────────────────────────────────────┘
+```
+
+## 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.
+
+**Input:**
+```json
+{
+  "skill": "mcp-server-ts",
+  "path": "snippets/tools/echo.ts"
+}
+```
+
+**Output:** File content.
+
+**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://` | 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 |
+
+### 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 (10MB max)
+- 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)
+
+## Server Instructions Format
+
+The server generates [instructions](https://blog.modelcontextprotocol.io/posts/2025-11-03-using-server-instructions/) that include a usage preamble and skill metadata:
+
+```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>
+```
+
+These are loaded into the model's system prompt by [clients](https://modelcontextprotocol.io/clients) that support instructions.
+
+## Skill Discovery
+
+Skills are discovered at startup from the configured 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.dev)
+- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
+- [Example MCP Clients](https://modelcontextprotocol.io/clients)

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+ * Skill Jack 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:
+ *   skill-jack-mcp /path/to/skills    # Skills directory (required)
+ *   SKILLS_DIR=/path/to/skills skill-jack-mcp
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+/**
+ * Skill Jack 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:
+ *   skill-jack-mcp /path/to/skills    # Skills directory (required)
+ *   SKILLS_DIR=/path/to/skills skill-jack-mcp
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+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 { registerSkillResources } from "./skill-resources.js";
+import { createSubscriptionManager, registerSubscriptionHandlers, } from "./subscriptions.js";
+/**
+ * Subdirectories to check for skills within the configured directory.
+ */
+const SKILL_SUBDIRS = [".claude/skills", "skills"];
+/**
+ * Get the skills directory from command line args or environment.
+ */
+function getSkillsDir() {
+    // Check command line argument first
+    const args = process.argv.slice(2);
+    if (args.length > 0 && args[0] && !args[0].startsWith("-")) {
+        return path.resolve(args[0]);
+    }
+    // Fall back to environment variable
+    const envDir = process.env.SKILLS_DIR;
+    if (envDir) {
+        return path.resolve(envDir);
+    }
+    return null;
+}
+/**
+ * Shared state for skill management.
+ * Tools and resources reference this state.
+ */
+const skillState = {
+    skillMap: new Map(),
+    instructions: "",
+};
+/**
+ * Discover skills from configured directory.
+ * Checks both the directory itself and standard subdirectories.
+ */
+function discoverSkillsFromDir(skillsDir) {
+    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);
+        }
+    }
+    return allSkills;
+}
+/**
+ * Subscription manager for resource file watching.
+ */
+const subscriptionManager = createSubscriptionManager();
+async function main() {
+    const skillsDir = getSkillsDir();
+    if (!skillsDir) {
+        console.error("No skills directory configured.");
+        console.error("Usage: skill-jack-mcp /path/to/skills");
+        console.error("   or: SKILLS_DIR=/path/to/skills skill-jack-mcp");
+        process.exit(1);
+    }
+    console.error(`Skills directory: ${skillsDir}`);
+    // Discover skills at startup
+    const skills = discoverSkillsFromDir(skillsDir);
+    skillState.skillMap = createSkillMap(skills);
+    skillState.instructions = generateInstructions(skills);
+    console.error(`Discovered ${skills.length} skill(s)`);
+    // Create the MCP server
+    const server = new McpServer({
+        name: "skill-jack-mcp",
+        version: "1.0.0",
+    }, {
+        capabilities: {
+            tools: {},
+            resources: { subscribe: true, listChanged: true },
+        },
+        instructions: skillState.instructions,
+    });
+    // Register tools and resources
+    registerSkillTool(server, skillState);
+    registerSkillResources(server, skillState);
+    // Register subscription handlers for resource file watching
+    registerSubscriptionHandlers(server, skillState, subscriptionManager);
+    // Connect via stdio transport
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Skill Jack 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>;

package/dist/roots-handler.js

@@ -0,0 +1,199 @@
+/**
+ * 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 { RootsListChangedNotificationSchema } from "@modelcontextprotocol/sdk/types.js";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { discoverSkills, generateInstructions, createSkillMap, } from "./skill-discovery.js";
+/**
+ * Skill discovery locations within each root.
+ */
+export const SKILL_SUBDIRS = [".claude/skills", "skills"];
+/**
+ * Convert a file:// URI to a filesystem path.
+ * Adapted from mcp-client-ts roots.ts pathToRoot() (reverse direction).
+ */
+function uriToPath(uri) {
+    return fileURLToPath(new URL(uri));
+}
+/**
+ * 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 function discoverSkillsFromRoots(roots) {
+    const allSkills = [];
+    const rootSources = new Map(); // skill path -> root name
+    const nameCount = new Map(); // track duplicates
+    for (const root of roots) {
+        let rootPath;
+        try {
+            rootPath = uriToPath(root.uri);
+        }
+        catch (error) {
+            console.error(`Failed to parse root URI "${root.uri}":`, error);
+            continue;
+        }
+        const rootName = root.name || path.basename(rootPath);
+        for (const subdir of SKILL_SUBDIRS) {
+            const skillsDir = path.join(rootPath, subdir);
+            if (fs.existsSync(skillsDir)) {
+                try {
+                    const skills = discoverSkills(skillsDir);
+                    for (const skill of skills) {
+                        // Track which root this skill came from
+                        rootSources.set(skill.path, rootName);
+                        // Count occurrences of each name
+                        const count = (nameCount.get(skill.name) || 0) + 1;
+                        nameCount.set(skill.name, count);
+                        allSkills.push(skill);
+                    }
+                }
+                catch (error) {
+                    console.error(`Failed to discover skills in "${skillsDir}":`, error);
+                }
+            }
+        }
+    }
+    // Handle naming conflicts by prefixing duplicates with root name
+    for (const skill of allSkills) {
+        if (nameCount.get(skill.name) > 1) {
+            const rootName = rootSources.get(skill.path);
+            skill.name = `${rootName}:${skill.name}`;
+        }
+    }
+    return { skills: allSkills, rootSources };
+}
+/**
+ * Discover skills from a directory, checking both the directory itself
+ * and SKILL_SUBDIRS subdirectories.
+ */
+function discoverSkillsFromDirectory(skillsDir) {
+    const allSkills = [];
+    // Check if the directory itself contains skills
+    const directSkills = discoverSkills(skillsDir);
+    allSkills.push(...directSkills);
+    // Also check SKILL_SUBDIRS subdirectories
+    for (const subdir of SKILL_SUBDIRS) {
+        const subPath = path.join(skillsDir, subdir);
+        if (fs.existsSync(subPath)) {
+            const subdirSkills = discoverSkills(subPath);
+            allSkills.push(...subdirSkills);
+        }
+    }
+    return allSkills;
+}
+/**
+ * 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 async function syncSkills(server, skillsDir, onSkillsChanged) {
+    const capabilities = server.server.getClientCapabilities();
+    const allSkills = [];
+    const seenNames = new Set();
+    // Always discover from configured skills directory first
+    if (skillsDir) {
+        const dirSkills = discoverSkillsFromDirectory(skillsDir);
+        console.error(`Discovered ${dirSkills.length} skill(s) from skills directory`);
+        for (const skill of dirSkills) {
+            if (!seenNames.has(skill.name)) {
+                seenNames.add(skill.name);
+                allSkills.push(skill);
+            }
+        }
+    }
+    // Also discover from roots if client supports them
+    if (capabilities?.roots) {
+        console.error("Client supports roots, requesting workspace roots...");
+        try {
+            const { roots } = await server.server.listRoots();
+            console.error(`Received ${roots.length} root(s) from client`);
+            const { skills: rootSkills } = discoverSkillsFromRoots(roots);
+            console.error(`Discovered ${rootSkills.length} skill(s) from roots`);
+            // Add roots skills, skipping duplicates (skillsDir takes precedence)
+            for (const skill of rootSkills) {
+                if (!seenNames.has(skill.name)) {
+                    seenNames.add(skill.name);
+                    allSkills.push(skill);
+                }
+            }
+            // Listen for roots changes if client supports listChanged
+            if (capabilities.roots.listChanged) {
+                setupRootsChangeHandler(server, skillsDir, onSkillsChanged);
+            }
+        }
+        catch (error) {
+            console.error("Failed to get roots from client:", error);
+        }
+    }
+    else {
+        console.error("Client does not support roots");
+    }
+    console.error(`Total skills available: ${allSkills.length}`);
+    const skillMap = createSkillMap(allSkills);
+    const instructions = generateInstructions(allSkills);
+    onSkillsChanged(skillMap, instructions);
+}
+/**
+ * Set up handler for roots/list_changed notifications.
+ */
+function setupRootsChangeHandler(server, skillsDir, onSkillsChanged) {
+    server.server.setNotificationHandler(RootsListChangedNotificationSchema, async () => {
+        console.error("Roots changed notification received, re-discovering skills...");
+        try {
+            const allSkills = [];
+            const seenNames = new Set();
+            // Always include skills from configured directory first
+            if (skillsDir) {
+                const dirSkills = discoverSkillsFromDirectory(skillsDir);
+                for (const skill of dirSkills) {
+                    if (!seenNames.has(skill.name)) {
+                        seenNames.add(skill.name);
+                        allSkills.push(skill);
+                    }
+                }
+            }
+            // Add skills from roots
+            const { roots } = await server.server.listRoots();
+            const { skills: rootSkills } = discoverSkillsFromRoots(roots);
+            console.error(`Re-discovered ${rootSkills.length} skill(s) from updated roots`);
+            for (const skill of rootSkills) {
+                if (!seenNames.has(skill.name)) {
+                    seenNames.add(skill.name);
+                    allSkills.push(skill);
+                }
+            }
+            console.error(`Total skills available: ${allSkills.length}`);
+            const skillMap = createSkillMap(allSkills);
+            const instructions = generateInstructions(allSkills);
+            onSkillsChanged(skillMap, instructions);
+            // Notify client that resources have changed
+            await server.server.notification({
+                method: "notifications/resources/list_changed",
+            });
+        }
+        catch (error) {
+            console.error("Failed to re-discover skills after roots change:", error);
+        }
+    });
+}

package/dist/skill-discovery.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Skill discovery and metadata parsing module.
+ *
+ * Discovers Agent Skills from a directory, parses YAML frontmatter,
+ * and generates server instructions XML.
+ */
+/**
+ * Metadata extracted from a skill's SKILL.md frontmatter.
+ */
+export interface SkillMetadata {
+    name: string;
+    description: string;
+    path: string;
+}
+/**
+ * Discover all skills in a directory.
+ * Scans for subdirectories containing SKILL.md files.
+ */
+export declare function discoverSkills(skillsDir: string): SkillMetadata[];
+/**
+ * Generate the server instructions with available skills.
+ * Includes a brief preamble about skill usage following the Agent Skills spec.
+ */
+export declare function generateInstructions(skills: SkillMetadata[]): string;
+/**
+ * Load the full content of a skill's SKILL.md file.
+ */
+export declare function loadSkillContent(skillPath: string): string;
+/**
+ * Create a map from skill name to skill metadata for fast lookup.
+ */
+export declare function createSkillMap(skills: SkillMetadata[]): Map<string, SkillMetadata>;