@olaservo/skill-jack-mcp 0.1.0

package/dist/skill-discovery.js

@@ -0,0 +1,136 @@
+/**
+ * Skill discovery and metadata parsing module.
+ *
+ * Discovers Agent Skills from a directory, parses YAML frontmatter,
+ * and generates server instructions XML.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { parse as parseYaml } from "yaml";
+/**
+ * Find the SKILL.md file in a skill directory.
+ * Prefers SKILL.md (uppercase) but accepts skill.md (lowercase).
+ */
+function findSkillMd(skillDir) {
+    for (const name of ["SKILL.md", "skill.md"]) {
+        const filePath = path.join(skillDir, name);
+        if (fs.existsSync(filePath)) {
+            return filePath;
+        }
+    }
+    return null;
+}
+/**
+ * Parse YAML frontmatter from SKILL.md content.
+ * Returns the parsed metadata and the markdown body.
+ */
+function parseFrontmatter(content) {
+    if (!content.startsWith("---")) {
+        throw new Error("SKILL.md must start with YAML frontmatter (---)");
+    }
+    const parts = content.split("---");
+    if (parts.length < 3) {
+        throw new Error("SKILL.md frontmatter not properly closed with ---");
+    }
+    const frontmatterStr = parts[1];
+    const body = parts.slice(2).join("---").trim();
+    const metadata = parseYaml(frontmatterStr);
+    if (typeof metadata !== "object" || metadata === null) {
+        throw new Error("SKILL.md frontmatter must be a YAML mapping");
+    }
+    return { metadata, body };
+}
+/**
+ * Discover all skills in a directory.
+ * Scans for subdirectories containing SKILL.md files.
+ */
+export function discoverSkills(skillsDir) {
+    const skills = [];
+    if (!fs.existsSync(skillsDir)) {
+        console.error(`Skills directory not found: ${skillsDir}`);
+        return skills;
+    }
+    const entries = fs.readdirSync(skillsDir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const skillDir = path.join(skillsDir, entry.name);
+        const skillMdPath = findSkillMd(skillDir);
+        if (!skillMdPath)
+            continue;
+        try {
+            const content = fs.readFileSync(skillMdPath, "utf-8");
+            const { metadata } = parseFrontmatter(content);
+            const name = metadata.name;
+            const description = metadata.description;
+            if (typeof name !== "string" || !name.trim()) {
+                console.error(`Skill at ${skillDir}: missing or invalid 'name' field`);
+                continue;
+            }
+            if (typeof description !== "string" || !description.trim()) {
+                console.error(`Skill at ${skillDir}: missing or invalid 'description' field`);
+                continue;
+            }
+            skills.push({
+                name: name.trim(),
+                description: description.trim(),
+                path: skillMdPath,
+            });
+        }
+        catch (error) {
+            console.error(`Failed to parse skill at ${skillDir}:`, error);
+        }
+    }
+    return skills;
+}
+/**
+ * Escape special XML characters.
+ */
+function escapeXml(str) {
+    return str
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&apos;");
+}
+/**
+ * Generate the server instructions with available skills.
+ * Includes a brief preamble about skill usage following the Agent Skills spec.
+ */
+export function generateInstructions(skills) {
+    const preamble = `# Skills
+
+When a user's task matches a skill description below: 1) activate it, 2) follow its instructions completely.
+
+`;
+    if (skills.length === 0) {
+        return preamble + "<available_skills>\n</available_skills>";
+    }
+    const lines = ["<available_skills>"];
+    for (const skill of skills) {
+        lines.push("<skill>");
+        lines.push(`<name>${escapeXml(skill.name)}</name>`);
+        lines.push(`<description>${escapeXml(skill.description)}</description>`);
+        lines.push(`<location>${escapeXml(skill.path)}</location>`);
+        lines.push("</skill>");
+    }
+    lines.push("</available_skills>");
+    return preamble + lines.join("\n");
+}
+/**
+ * Load the full content of a skill's SKILL.md file.
+ */
+export function loadSkillContent(skillPath) {
+    return fs.readFileSync(skillPath, "utf-8");
+}
+/**
+ * Create a map from skill name to skill metadata for fast lookup.
+ */
+export function createSkillMap(skills) {
+    const map = new Map();
+    for (const skill of skills) {
+        map.set(skill.name, skill);
+    }
+    return map;
+}

package/dist/skill-resources.d.ts

@@ -0,0 +1,27 @@
+/**
+ * MCP Resource registration for skill-based resources.
+ *
+ * Resources provide application-controlled access to skill content,
+ * complementing the model-controlled tool access.
+ *
+ * All resources use templates with dynamic list callbacks to support
+ * 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}/{path}  -> File within skill directory (template)
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { SkillState } from "./skill-tool.js";
+/**
+ * Register skill resources with the MCP server.
+ *
+ * All resources use templates with dynamic list callbacks to support
+ * skill updates when MCP roots change.
+ *
+ * @param server - The McpServer instance
+ * @param skillState - Shared state object (allows dynamic updates)
+ */
+export declare function registerSkillResources(server: McpServer, skillState: SkillState): void;

package/dist/skill-resources.js

@@ -0,0 +1,239 @@
+/**
+ * MCP Resource registration for skill-based resources.
+ *
+ * Resources provide application-controlled access to skill content,
+ * complementing the model-controlled tool access.
+ *
+ * All resources use templates with dynamic list callbacks to support
+ * 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}/{path}  -> File within skill directory (template)
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { loadSkillContent } from "./skill-discovery.js";
+import { isPathWithinBase, listSkillFiles, MAX_FILE_SIZE } from "./skill-tool.js";
+/**
+ * Get MIME type based on file extension.
+ */
+function getMimeType(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    const mimeTypes = {
+        ".md": "text/markdown",
+        ".ts": "text/typescript",
+        ".js": "text/javascript",
+        ".json": "application/json",
+        ".yaml": "text/yaml",
+        ".yml": "text/yaml",
+        ".txt": "text/plain",
+        ".sh": "text/x-shellscript",
+        ".py": "text/x-python",
+        ".css": "text/css",
+        ".html": "text/html",
+        ".xml": "application/xml",
+    };
+    return mimeTypes[ext] || "text/plain";
+}
+/**
+ * Register skill resources with the MCP server.
+ *
+ * All resources use templates with dynamic list callbacks to support
+ * skill updates when MCP roots change.
+ *
+ * @param server - The McpServer instance
+ * @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 resource template for skill files
+    registerSkillFileTemplate(server, skillState);
+}
+/**
+ * Register a collection resource that returns all skills at once.
+ *
+ * URI: skill://
+ *
+ * Returns multiple ResourceContents, one per skill, each with its own URI.
+ * This allows clients to fetch all skill content in a single request.
+ */
+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 () => {
+        const contents = [];
+        for (const [name, skill] of skillState.skillMap) {
+            try {
+                const content = loadSkillContent(skill.path);
+                contents.push({
+                    uri: `skill://${encodeURIComponent(name)}`,
+                    mimeType: "text/markdown",
+                    text: content,
+                });
+            }
+            catch (error) {
+                // Skip skills that fail to load, but continue with others
+                console.error(`Failed to load skill "${name}":`, error);
+            }
+        }
+        return { contents };
+    });
+}
+/**
+ * Register a template for individual skill SKILL.md resources.
+ *
+ * URI Pattern: skill://{skillName}
+ *
+ * Uses a template with a list callback to dynamically return available skills.
+ */
+function registerSkillTemplate(server, skillState) {
+    server.registerResource("Skill", new ResourceTemplate("skill://{skillName}", {
+        list: async () => {
+            // Dynamically return current skills
+            const resources = [];
+            for (const [name, skill] of skillState.skillMap) {
+                resources.push({
+                    uri: `skill://${encodeURIComponent(name)}`,
+                    name,
+                    mimeType: "text/markdown",
+                    description: skill.description,
+                });
+            }
+            return { resources };
+        },
+        complete: {
+            skillName: (value) => {
+                const names = Array.from(skillState.skillMap.keys());
+                return names.filter((name) => name.toLowerCase().startsWith(value.toLowerCase()));
+            },
+        },
+    }), {
+        mimeType: "text/markdown",
+        description: "SKILL.md content for a skill",
+    }, async (resourceUri) => {
+        // Extract skill name from URI
+        const uriStr = resourceUri.toString();
+        const match = uriStr.match(/^skill:\/\/([^/]+)$/);
+        if (!match) {
+            throw new Error(`Invalid skill 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"}`);
+        }
+        try {
+            const content = loadSkillContent(skill.path);
+            return {
+                contents: [
+                    {
+                        uri: uriStr,
+                        mimeType: "text/markdown",
+                        text: content,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Failed to load skill "${skillName}": ${message}`);
+        }
+    });
+}
+/**
+ * Register the resource template for accessing files within skills.
+ *
+ * URI Pattern: skill://{skillName}/{filePath}
+ */
+function registerSkillFileTemplate(server, skillState) {
+    server.registerResource("Skill File", new ResourceTemplate("skill://{skillName}/{+filePath}", {
+        list: async () => {
+            // Return all listable skill files (dynamic based on current skillMap)
+            const resources = [];
+            for (const [name, skill] of skillState.skillMap) {
+                const skillDir = path.dirname(skill.path);
+                const files = listSkillFiles(skillDir);
+                for (const file of files) {
+                    const uri = `skill://${encodeURIComponent(name)}/${file}`;
+                    resources.push({
+                        uri,
+                        name: `${name}/${file}`,
+                        mimeType: getMimeType(file),
+                    });
+                }
+            }
+            return { resources };
+        },
+        complete: {
+            skillName: (value) => {
+                const names = Array.from(skillState.skillMap.keys());
+                return names.filter((name) => name.toLowerCase().startsWith(value.toLowerCase()));
+            },
+        },
+    }), {
+        mimeType: "text/plain",
+        description: "Files within a skill directory (scripts, snippets, assets, etc.)",
+    }, async (resourceUri, variables) => {
+        // Extract skill name and file path from URI
+        const uriStr = resourceUri.toString();
+        const match = uriStr.match(/^skill:\/\/([^/]+)\/(.+)$/);
+        if (!match) {
+            throw new Error(`Invalid skill file URI: ${uriStr}`);
+        }
+        const skillName = decodeURIComponent(match[1]);
+        const filePath = match[2];
+        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 fullPath = path.resolve(skillDir, filePath);
+        // Security: Validate path is within skill directory
+        if (!isPathWithinBase(fullPath, skillDir)) {
+            throw new Error(`Path "${filePath}" is outside the skill directory`);
+        }
+        // Check file exists
+        if (!fs.existsSync(fullPath)) {
+            const files = listSkillFiles(skillDir).slice(0, 10);
+            throw new Error(`File "${filePath}" not found in skill "${skillName}". ` +
+                `Available: ${files.join(", ")}${files.length >= 10 ? "..." : ""}`);
+        }
+        const stat = fs.statSync(fullPath);
+        // Reject symlinks
+        if (stat.isSymbolicLink()) {
+            throw new Error(`Cannot read symlink "${filePath}"`);
+        }
+        // Reject directories
+        if (stat.isDirectory()) {
+            const files = listSkillFiles(skillDir, filePath);
+            throw new Error(`"${filePath}" is a directory. Files within: ${files.join(", ")}`);
+        }
+        // Check file size
+        if (stat.size > MAX_FILE_SIZE) {
+            const sizeMB = (stat.size / 1024 / 1024).toFixed(2);
+            throw new Error(`File too large (${sizeMB}MB). Maximum: 10MB`);
+        }
+        // Read and return content
+        const content = fs.readFileSync(fullPath, "utf-8");
+        const mimeType = getMimeType(fullPath);
+        return {
+            contents: [
+                {
+                    uri: uriStr,
+                    mimeType,
+                    text: content,
+                },
+            ],
+        };
+    });
+}

package/dist/skill-tool.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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 { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { SkillMetadata } from "./skill-discovery.js";
+/**
+ * Shared state for dynamic skill management.
+ * Tools reference this state object, allowing updates when roots change.
+ */
+export interface SkillState {
+    skillMap: Map<string, SkillMetadata>;
+    instructions: string;
+}
+/**
+ * Register the "skill" tool with the MCP server.
+ *
+ * @param server - The McpServer instance
+ * @param skillState - Shared state object (allows dynamic updates)
+ */
+export declare function registerSkillTool(server: McpServer, skillState: SkillState): void;
+export declare const MAX_FILE_SIZE: number;
+export declare const MAX_DIRECTORY_DEPTH = 10;
+/**
+ * Check if a path is within the allowed base directory.
+ * Uses fs.realpathSync to resolve symlinks and prevent symlink escape attacks.
+ */
+export declare function isPathWithinBase(targetPath: string, baseDir: string): boolean;
+/**
+ * List files in a skill directory for discovery.
+ * Limits recursion depth to prevent DoS from deeply nested directories.
+ */
+export declare function listSkillFiles(skillDir: string, subPath?: string, depth?: number): string[];