local-skills-mcp 0.1.0

package/dist/index.js

@@ -0,0 +1,263 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import path from "path";
+import fs from "fs";
+import os from "os";
+import { fileURLToPath } from "url";
+import { SkillLoader } from "./skill-loader.js";
+// Get version from package.json (single source of truth)
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+const packageJson = JSON.parse(fs.readFileSync(path.join(__dirname, "../package.json"), "utf-8"));
+// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access
+const VERSION = packageJson.version;
+/**
+ * Get all skills directories to aggregate from.
+ *
+ * Scans for skill directories in the following order (lowest to highest priority):
+ * 1. `<package-root>/skills` - Package built-in skills (self-documenting, always available)
+ * 2. `~/.claude/skills` - Global Claude skills
+ * 3. `{cwd}/.claude/skills` - Project-level Claude skills
+ * 4. `{cwd}/skills` - Default project skills directory
+ * 5. `$SKILLS_DIR` - Custom directory from environment variable
+ *
+ * For duplicate skill names, later directories take precedence. This allows
+ * users to override built-in skills with their own versions.
+ *
+ * @returns Array of directory paths that exist on the filesystem
+ *
+ * @example
+ * ```typescript
+ * const dirs = getAllSkillsDirectories();
+ * console.log(dirs);
+ * // ['/usr/lib/node_modules/local-skills-mcp/skills', '/home/user/.claude/skills', '/home/user/project/skills']
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With SKILLS_DIR environment variable
+ * process.env.SKILLS_DIR = '/custom/skills';
+ * const dirs = getAllSkillsDirectories();
+ * // Returns: [...standard paths..., '/custom/skills']
+ * ```
+ */
+export function getAllSkillsDirectories() {
+    const directories = [];
+    // Always include package built-in skills first (lowest priority, always available)
+    // This provides self-documenting capabilities out-of-the-box
+    const packageRoot = path.join(__dirname, "..");
+    const packageSkills = path.join(packageRoot, "skills");
+    if (fs.existsSync(packageSkills)) {
+        directories.push(packageSkills);
+    }
+    // Include standard Claude locations if they exist
+    const homeClaudeSkills = path.join(os.homedir(), ".claude", "skills");
+    if (fs.existsSync(homeClaudeSkills)) {
+        directories.push(homeClaudeSkills);
+    }
+    const projectClaudeSkills = path.join(process.cwd(), ".claude", "skills");
+    if (fs.existsSync(projectClaudeSkills)) {
+        directories.push(projectClaudeSkills);
+    }
+    const defaultSkills = path.join(process.cwd(), "skills");
+    if (fs.existsSync(defaultSkills)) {
+        directories.push(defaultSkills);
+    }
+    // If SKILLS_DIR is set, add it (it takes precedence for duplicates)
+    if (process.env.SKILLS_DIR) {
+        directories.push(process.env.SKILLS_DIR);
+    }
+    return directories;
+}
+const SKILLS_DIRS = getAllSkillsDirectories();
+/**
+ * Main MCP server class for serving skills to AI clients.
+ *
+ * LocalSkillsServer handles MCP protocol communication, manages skill discovery
+ * and loading through SkillLoader, and formats responses for clients.
+ *
+ * @example
+ * ```typescript
+ * const server = new LocalSkillsServer();
+ * await server.run();
+ * // Server is now running and listening on stdio
+ * ```
+ */
+export class LocalSkillsServer {
+    server;
+    skillLoader;
+    /**
+     * Creates a new LocalSkillsServer instance.
+     *
+     * Initializes the MCP server with capabilities, creates a SkillLoader
+     * for all configured directories, and sets up request handlers.
+     */
+    constructor() {
+        this.server = new Server({
+            name: "local-skills-mcp",
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+            version: VERSION,
+        }, {
+            capabilities: {
+                tools: {},
+            },
+        });
+        this.skillLoader = new SkillLoader(SKILLS_DIRS);
+        this.setupHandlers();
+        this.setupErrorHandling();
+    }
+    setupErrorHandling() {
+        this.server.onerror = (error) => {
+            console.error("[MCP Error]", error);
+        };
+        // eslint-disable-next-line @typescript-eslint/no-misused-promises
+        process.on("SIGINT", async () => {
+            await this.server.close();
+            process.exit(0);
+        });
+    }
+    setupHandlers() {
+        // List available tools (dynamically generated to include current skill list)
+        this.server.setRequestHandler(ListToolsRequestSchema, async () => {
+            // Discover skills to get current list
+            const skillNames = await this.skillLoader.discoverSkills();
+            // Build enhanced description for get_skill following Claude Skills best practices
+            // Pattern: [What it does]. [Value proposition]. Use when [trigger conditions].
+            let getSkillDescription = "Loads specialized expert prompt instructions that transform your capabilities for specific tasks. " +
+                "Each skill provides comprehensive guidance, proven methodologies, and domain-specific best practices. " +
+                "Use when you need focused expertise, systematic approaches, or professional standards for any task that would benefit from specialized knowledge. " +
+                "Invoke with the skill name to receive detailed instructions that enhance your problem-solving approach with structured, expert-level guidance.";
+            // Package built-in skills ensure there are always skills available
+            if (skillNames.length > 0) {
+                getSkillDescription += `\n\nAvailable skills: ${skillNames.join(", ")}`;
+            }
+            const tools = [
+                {
+                    name: "get_skill",
+                    description: getSkillDescription,
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            skill_name: {
+                                type: "string",
+                                description: 'The name of the skill to retrieve (e.g., "code-reviewer", "test-generator")',
+                            },
+                        },
+                        required: ["skill_name"],
+                    },
+                },
+            ];
+            return { tools };
+        });
+        // Handle tool calls
+        this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+            try {
+                switch (request.params.name) {
+                    case "get_skill":
+                        return await this.handleGetSkill(request.params.arguments);
+                    default:
+                        throw new Error(`Unknown tool: ${request.params.name}`);
+                }
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Error: ${errorMessage}`,
+                        },
+                    ],
+                };
+            }
+        });
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    async handleGetSkill(args) {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access
+        const skillName = args?.skill_name;
+        if (!skillName) {
+            throw new Error("skill_name is required");
+        }
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+        const skill = await this.skillLoader.loadSkill(skillName);
+        const output = [
+            `# Skill: ${skill.name}`,
+            ``,
+            `**Description:** ${skill.description}`,
+            `**Source:** ${skill.source}`,
+            ``,
+            `---`,
+            ``,
+            skill.content,
+        ];
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: output.join("\n"),
+                },
+            ],
+        };
+    }
+    /**
+     * Starts the MCP server and connects it to stdio transport.
+     *
+     * This method initializes the stdio transport for MCP communication,
+     * connects the server, and logs startup information including the
+     * list of skill directories being monitored.
+     *
+     * @throws {Error} If the server fails to connect or start
+     *
+     * @example
+     * ```typescript
+     * const server = new LocalSkillsServer();
+     * await server.run();
+     * // Output to stderr:
+     * // Local Skills MCP Server v0.1.0 running on stdio
+     * // Aggregating skills from 3 directories:
+     * //   - /home/user/.claude/skills
+     * //   - /home/user/project/.claude/skills
+     * //   - /home/user/project/skills
+     * ```
+     */
+    async run() {
+        const transport = new StdioServerTransport();
+        await this.server.connect(transport);
+        console.error(`Local Skills MCP Server v${VERSION} running on stdio`);
+        console.error(`Aggregating skills from ${SKILLS_DIRS.length} director${SKILLS_DIRS.length === 1 ? "y" : "ies"}:`);
+        SKILLS_DIRS.forEach((dir) => console.error(`  - ${dir}`));
+    }
+    /**
+     * Closes the server and releases all resources.
+     *
+     * This method properly shuts down the MCP server and waits for all
+     * file handles and resources to be released. This is particularly
+     * important on Windows where file handles may take longer to release.
+     *
+     * @example
+     * ```typescript
+     * const server = new LocalSkillsServer();
+     * await server.run();
+     * // ... do work ...
+     * await server.close();
+     * ```
+     */
+    async close() {
+        await this.server.close();
+        // Allow time for all handles to be released (important on Windows)
+        await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+}
+// Start the server only if this module is being run directly
+/* istanbul ignore if */
+if (import.meta.url === `file://${process.argv[1]}`) {
+    const server = new LocalSkillsServer();
+    server.run().catch((error) => {
+        console.error("Fatal error running server:", error);
+        process.exit(1);
+    });
+}

package/dist/skill-loader.d.ts

@@ -0,0 +1,126 @@
+import { Skill, SkillMetadata } from "./types.js";
+/**
+ * Manages skill discovery and loading across multiple directories.
+ *
+ * SkillLoader is responsible for:
+ * - Discovering skills in configured directories
+ * - Loading and parsing SKILL.md files with YAML frontmatter
+ * - Managing the skill registry for fast lookups
+ *
+ * Skills are loaded fresh from disk on each request to support hot reload.
+ *
+ * @example
+ * ```typescript
+ * const loader = new SkillLoader([
+ *   '/home/user/.claude/skills',
+ *   '/home/user/project/skills'
+ * ]);
+ * const skills = await loader.discoverSkills();
+ * const skill = await loader.loadSkill('code-reviewer');
+ * ```
+ */
+export declare class SkillLoader {
+    private skillsPaths;
+    private skillRegistry;
+    /**
+     * Creates a new SkillLoader instance.
+     *
+     * @param skillsPaths - Array of directory paths to search for skills
+     *
+     * @example
+     * ```typescript
+     * const loader = new SkillLoader([
+     *   '/home/user/.claude/skills',
+     *   '/home/user/project/skills'
+     * ]);
+     * ```
+     */
+    constructor(skillsPaths: string[]);
+    /**
+     * Parse SKILL.md file with YAML frontmatter
+     */
+    private parseSkillFile;
+    /**
+     * Discover all available skills aggregated from all directories.
+     *
+     * Scans all configured directories for subdirectories containing SKILL.md files.
+     * Later directories override earlier ones for duplicate skill names.
+     * The internal skill registry is rebuilt on each call.
+     *
+     * @returns Promise resolving to a sorted array of skill names
+     *
+     * @example
+     * ```typescript
+     * const skillNames = await loader.discoverSkills();
+     * console.log(skillNames);
+     * // Output: ['code-reviewer', 'test-generator', 'refactoring-expert']
+     * ```
+     */
+    discoverSkills(): Promise<string[]>;
+    /**
+     * Load a specific skill by name, reading fresh from disk each time.
+     *
+     * Loads the SKILL.md file, parses YAML frontmatter, and validates metadata.
+     * Skills are always read fresh to support hot reload of content changes.
+     *
+     * @param skillName - The name of the skill to load
+     * @returns Promise resolving to the complete Skill object
+     * @throws {Error} If skill is not found in registry or file cannot be loaded/parsed
+     *
+     * @example
+     * ```typescript
+     * const skill = await loader.loadSkill('code-reviewer');
+     * console.log(skill.name);        // 'Code Reviewer'
+     * console.log(skill.description); // 'Expert code review assistant'
+     * console.log(skill.content);     // Full skill prompt content
+     * console.log(skill.source);      // '/home/user/.claude/skills'
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Error handling
+     * try {
+     *   const skill = await loader.loadSkill('non-existent');
+     * } catch (error) {
+     *   console.error(error.message);
+     *   // "Skill "non-existent" not found. Run list_skills to see available skills."
+     * }
+     * ```
+     */
+    loadSkill(skillName: string): Promise<Skill>;
+    /**
+     * Get skill metadata without loading the full content.
+     *
+     * Lightweight operation that loads only the YAML frontmatter without
+     * the full skill content. Useful for listing skills with descriptions.
+     *
+     * @param skillName - The name of the skill
+     * @returns Promise resolving to metadata with source directory
+     * @throws {Error} If skill is not found or metadata cannot be loaded
+     *
+     * @example
+     * ```typescript
+     * const metadata = await loader.getSkillMetadata('code-reviewer');
+     * console.log(metadata.name);        // 'Code Reviewer'
+     * console.log(metadata.description); // 'Expert code review assistant'
+     * console.log(metadata.source);      // '/home/user/.claude/skills'
+     * // Note: metadata does not include 'content' field
+     * ```
+     */
+    getSkillMetadata(skillName: string): Promise<SkillMetadata & {
+        source: string;
+    }>;
+    /**
+     * Get all skills directories being monitored.
+     *
+     * @returns Array of directory paths configured for this loader
+     *
+     * @example
+     * ```typescript
+     * const paths = loader.getSkillsPaths();
+     * console.log(paths);
+     * // Output: ['/home/user/.claude/skills', '/home/user/project/skills']
+     * ```
+     */
+    getSkillsPaths(): string[];
+}

package/dist/skill-loader.js

@@ -0,0 +1,231 @@
+import fs from "fs/promises";
+import path from "path";
+import YAML from "yaml";
+/**
+ * Manages skill discovery and loading across multiple directories.
+ *
+ * SkillLoader is responsible for:
+ * - Discovering skills in configured directories
+ * - Loading and parsing SKILL.md files with YAML frontmatter
+ * - Managing the skill registry for fast lookups
+ *
+ * Skills are loaded fresh from disk on each request to support hot reload.
+ *
+ * @example
+ * ```typescript
+ * const loader = new SkillLoader([
+ *   '/home/user/.claude/skills',
+ *   '/home/user/project/skills'
+ * ]);
+ * const skills = await loader.discoverSkills();
+ * const skill = await loader.loadSkill('code-reviewer');
+ * ```
+ */
+export class SkillLoader {
+    skillsPaths;
+    skillRegistry = new Map();
+    /**
+     * Creates a new SkillLoader instance.
+     *
+     * @param skillsPaths - Array of directory paths to search for skills
+     *
+     * @example
+     * ```typescript
+     * const loader = new SkillLoader([
+     *   '/home/user/.claude/skills',
+     *   '/home/user/project/skills'
+     * ]);
+     * ```
+     */
+    constructor(skillsPaths) {
+        this.skillsPaths = skillsPaths;
+    }
+    /**
+     * Parse SKILL.md file with YAML frontmatter
+     */
+    parseSkillFile(content) {
+        // Check if file starts with frontmatter delimiter
+        if (!content.startsWith("---\n")) {
+            throw new Error("SKILL.md must start with YAML frontmatter (---)");
+        }
+        // Find the closing delimiter
+        const endDelimiterIndex = content.indexOf("\n---\n", 4);
+        if (endDelimiterIndex === -1) {
+            throw new Error("SKILL.md frontmatter must end with --- delimiter");
+        }
+        // Extract and parse YAML frontmatter
+        const frontmatterText = content.substring(4, endDelimiterIndex);
+        const metadata = YAML.parse(frontmatterText);
+        // Validate required fields
+        if (!metadata.name) {
+            throw new Error('SKILL.md frontmatter must include "name" field');
+        }
+        if (!metadata.description) {
+            throw new Error('SKILL.md frontmatter must include "description" field');
+        }
+        // Extract content after frontmatter
+        const skillContent = content.substring(endDelimiterIndex + 5).trim();
+        return { metadata, content: skillContent };
+    }
+    /**
+     * Discover all available skills aggregated from all directories.
+     *
+     * Scans all configured directories for subdirectories containing SKILL.md files.
+     * Later directories override earlier ones for duplicate skill names.
+     * The internal skill registry is rebuilt on each call.
+     *
+     * @returns Promise resolving to a sorted array of skill names
+     *
+     * @example
+     * ```typescript
+     * const skillNames = await loader.discoverSkills();
+     * console.log(skillNames);
+     * // Output: ['code-reviewer', 'test-generator', 'refactoring-expert']
+     * ```
+     */
+    async discoverSkills() {
+        this.skillRegistry.clear();
+        const allSkills = new Map();
+        // Iterate through all skill directories
+        for (const skillsPath of this.skillsPaths) {
+            try {
+                const entries = await fs.readdir(skillsPath, { withFileTypes: true });
+                for (const entry of entries) {
+                    if (entry.isDirectory()) {
+                        const skillPath = path.join(skillsPath, entry.name);
+                        const skillFilePath = path.join(skillPath, "SKILL.md");
+                        try {
+                            await fs.access(skillFilePath);
+                            // Later directories override earlier ones for duplicate names
+                            allSkills.set(entry.name, {
+                                path: skillPath,
+                                source: skillsPath,
+                            });
+                        }
+                        catch {
+                            // Skip directories without SKILL.md
+                            continue;
+                        }
+                    }
+                }
+            }
+            catch (error) {
+                if (error.code !== "ENOENT") {
+                    console.error(`Error reading directory ${skillsPath}:`, error);
+                }
+                // Continue with other directories even if one fails
+                continue;
+            }
+        }
+        // Update registry
+        this.skillRegistry = allSkills;
+        // Return sorted skill names
+        return Array.from(allSkills.keys()).sort();
+    }
+    /**
+     * Load a specific skill by name, reading fresh from disk each time.
+     *
+     * Loads the SKILL.md file, parses YAML frontmatter, and validates metadata.
+     * Skills are always read fresh to support hot reload of content changes.
+     *
+     * @param skillName - The name of the skill to load
+     * @returns Promise resolving to the complete Skill object
+     * @throws {Error} If skill is not found in registry or file cannot be loaded/parsed
+     *
+     * @example
+     * ```typescript
+     * const skill = await loader.loadSkill('code-reviewer');
+     * console.log(skill.name);        // 'Code Reviewer'
+     * console.log(skill.description); // 'Expert code review assistant'
+     * console.log(skill.content);     // Full skill prompt content
+     * console.log(skill.source);      // '/home/user/.claude/skills'
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Error handling
+     * try {
+     *   const skill = await loader.loadSkill('non-existent');
+     * } catch (error) {
+     *   console.error(error.message);
+     *   // "Skill "non-existent" not found. Run list_skills to see available skills."
+     * }
+     * ```
+     */
+    async loadSkill(skillName) {
+        // Get skill location from registry
+        const skillInfo = this.skillRegistry.get(skillName);
+        if (!skillInfo) {
+            throw new Error(`Skill "${skillName}" not found. Run list_skills to see available skills.`);
+        }
+        const skillFilePath = path.join(skillInfo.path, "SKILL.md");
+        try {
+            // Load and parse SKILL.md fresh from disk
+            const fileContent = await fs.readFile(skillFilePath, "utf-8");
+            const { metadata, content } = this.parseSkillFile(fileContent);
+            const skill = {
+                name: metadata.name,
+                description: metadata.description,
+                content,
+                path: skillInfo.path,
+                source: skillInfo.source,
+            };
+            return skill;
+        }
+        catch (error) {
+            throw new Error(`Failed to load skill "${skillName}": ${error.message}`);
+        }
+    }
+    /**
+     * Get skill metadata without loading the full content.
+     *
+     * Lightweight operation that loads only the YAML frontmatter without
+     * the full skill content. Useful for listing skills with descriptions.
+     *
+     * @param skillName - The name of the skill
+     * @returns Promise resolving to metadata with source directory
+     * @throws {Error} If skill is not found or metadata cannot be loaded
+     *
+     * @example
+     * ```typescript
+     * const metadata = await loader.getSkillMetadata('code-reviewer');
+     * console.log(metadata.name);        // 'Code Reviewer'
+     * console.log(metadata.description); // 'Expert code review assistant'
+     * console.log(metadata.source);      // '/home/user/.claude/skills'
+     * // Note: metadata does not include 'content' field
+     * ```
+     */
+    async getSkillMetadata(skillName) {
+        const skillInfo = this.skillRegistry.get(skillName);
+        if (!skillInfo) {
+            throw new Error(`Skill "${skillName}" not found`);
+        }
+        const skillFilePath = path.join(skillInfo.path, "SKILL.md");
+        try {
+            const fileContent = await fs.readFile(skillFilePath, "utf-8");
+            const { metadata } = this.parseSkillFile(fileContent);
+            return {
+                ...metadata,
+                source: skillInfo.source,
+            };
+        }
+        catch (error) {
+            throw new Error(`Failed to load metadata for skill "${skillName}": ${error.message}`);
+        }
+    }
+    /**
+     * Get all skills directories being monitored.
+     *
+     * @returns Array of directory paths configured for this loader
+     *
+     * @example
+     * ```typescript
+     * const paths = loader.getSkillsPaths();
+     * console.log(paths);
+     * // Output: ['/home/user/.claude/skills', '/home/user/project/skills']
+     * ```
+     */
+    getSkillsPaths() {
+        return this.skillsPaths;
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Skill metadata from YAML frontmatter in SKILL.md
+ */
+export interface SkillMetadata {
+    name: string;
+    description: string;
+}
+/**
+ * Full skill definition including prompt content
+ */
+export interface Skill {
+    name: string;
+    description: string;
+    content: string;
+    path: string;
+    source: string;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};