@open-skills-hub/mcp-server 1.0.0

package/dist/index.js

@@ -0,0 +1,1490 @@
+#!/usr/bin/env node
+/**
+ * SkillsHub MCP Server
+ *
+ * Model Context Protocol (MCP) server for AI Agent Skills management.
+ *
+ * This server enables AI agents to discover, retrieve, publish, and manage
+ * reusable skills through a standardized protocol. Think of it as "npm for AI agents"
+ * - a centralized hub for sharing and discovering agent capabilities.
+ *
+ * Features:
+ * - 🔍 Search skills by keywords, category, or author
+ * - 📥 Retrieve complete skill content with all attachments
+ * - 📤 Publish new skills or update existing ones
+ * - 🔒 Security scanning with built-in SkillsGuard rules
+ * - 💬 Feedback system for skill quality improvement
+ * - 💾 Local caching for offline usage
+ * - 📦 Install skills directly into projects
+ *
+ * Architecture:
+ * - Local-first: All data stored in SQLite, no cloud dependency
+ * - Secure: Automatic security scanning on publish
+ * - Versioned: Full semantic versioning support
+ * - Async feedback: Offline feedback queue with auto-retry
+ *
+ * @see https://github.com/OpenSkillsHub/open-skills-hub
+ * @see https://modelcontextprotocol.io
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } from '@modelcontextprotocol/sdk/types.js';
+import * as fs from 'fs';
+import * as path from 'path';
+import { parse as parseYaml } from 'yaml';
+import { initConfig, getStorage, initScanner, getScanner, parseSkillFullName, buildSkillFullName, generateUUID, now, sha256, isValidSkillName, isValidSemver, logger, } from '@open-skills-hub/core';
+import { FeedbackQueueProcessor } from './queue.js';
+// Server info
+const SERVER_NAME = 'open-skills-hub';
+const SERVER_VERSION = '1.0.0';
+// HTTP client for API reload
+async function reloadApi(apiUrl) {
+    try {
+        // Remove trailing slash and ensure http:// prefix
+        const url = apiUrl.replace(/\/$/, '');
+        logger.info(`Attempting to reload API at ${url}/reload`);
+        const response = await fetch(`${url}/reload`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+            },
+        });
+        if (response.ok) {
+            logger.info('API reloaded successfully');
+        }
+        else {
+            logger.warn(`Failed to reload API: ${response.status} ${response.statusText}`);
+        }
+    }
+    catch (error) {
+        // Don't fail the publish operation if reload fails
+        logger.warn('Failed to call API reload', { error });
+    }
+}
+/**
+ * Create and configure the MCP server
+ */
+async function createMcpServer() {
+    // Initialize config
+    const config = initConfig();
+    await config.load();
+    // Initialize storage
+    const storage = await getStorage();
+    await storage.initialize();
+    // Initialize scanner
+    initScanner({
+        enabled: config.get().scanner.enabled,
+        timeout: config.get().scanner.timeout,
+        maxFileSize: config.get().scanner.maxFileSize,
+    });
+    // Start feedback queue processor
+    const queueProcessor = new FeedbackQueueProcessor(storage, config.get().retry);
+    queueProcessor.start();
+    // Create MCP server
+    const server = new Server({
+        name: SERVER_NAME,
+        version: SERVER_VERSION,
+    }, {
+        capabilities: {
+            tools: {},
+        },
+    });
+    // ============================================================================
+    // MCP Tools Registration
+    // ============================================================================
+    // 
+    // SkillsHub provides 7 core tools for managing AI Agent Skills:
+    // 
+    // Discovery & Retrieval:
+    //   - skills_search: Find skills by keywords, category, or author
+    //   - skills_get: Retrieve complete skill content with attachments
+    //   - skills_list_cached: View locally cached skills
+    // 
+    // Publishing & Installation:
+    //   - skills_publish: Upload skills to the hub
+    //   - skills_install: Download and install skills to projects
+    // 
+    // Quality & Safety:
+    //   - skills_scan: Security scanning with SkillsGuard
+    //   - skills_feedback: Submit ratings and feedback
+    // 
+    // All tools use clear, explicit parameter names and provide detailed
+    // error messages to help AI agents use them correctly.
+    // 
+    // ============================================================================
+    // Register tool handlers
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: [
+            {
+                name: 'skills_search',
+                description: 'Search Agent Skills: Find skills by keywords, category, or author. Returns a list where each skill has a "Name" field (e.g., "@official/xlsx") that should be used as the "name" parameter in skills_install or skills_get.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        query: {
+                            type: 'string',
+                            description: 'Search query - can be skill name, description keywords, or feature characteristics. Leave EMPTY ("") to list all skills. DO NOT use wildcards like "*" or "%" - they will be treated as literal characters. Examples: "" (all skills), "calculator", "API", "design", "pdf"',
+                        },
+                        category: {
+                            type: 'string',
+                            description: 'Filter by category. Examples: "utility", "development", "design"',
+                        },
+                        author: {
+                            type: 'string',
+                            description: 'Filter by author or organization. Examples: "@official", "@user", "@example"',
+                        },
+                        limit: {
+                            type: 'number',
+                            description: 'Maximum number of results to return. Default: 10, Maximum: 100. Use higher limit (e.g., 50-100) when listing all skills.',
+                        },
+                    },
+                },
+            },
+            {
+                name: 'skills_get',
+                description: 'Get complete skill content: Retrieve SKILL.md documentation, all attachments, metadata, and version information. Specify a version or get the latest. Use this before using a skill to understand its functionality.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        name: {
+                            type: 'string',
+                            description: 'REQUIRED. Full skill name (use the "Name" field from skills_search results). Valid formats: "calculator", "@user/calculator", "@official/code-reviewer".',
+                        },
+                        version: {
+                            type: 'string',
+                            description: 'Optional. Specific version to retrieve in semver format. Examples: "1.0.0", "2.1.3". If omitted, returns latest version.',
+                        },
+                    },
+                    required: ['name'],
+                },
+            },
+            {
+                name: 'skills_scan',
+                description: 'Security scan: Check skill content for potential security risks including malicious code, dangerous commands, and sensitive information leaks. Returns a security score (0-100) and detailed report.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        content: {
+                            type: 'string',
+                            description: 'REQUIRED. Text content to scan - typically SKILL.md content or script code.',
+                        },
+                    },
+                    required: ['content'],
+                },
+            },
+            {
+                name: 'skills_feedback',
+                description: 'Submit skill feedback: Help improve skill quality by reporting success, failure, suggestions, or bugs. Feedback is recorded and affects skill ratings.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        name: {
+                            type: 'string',
+                            description: 'REQUIRED. Full skill name with scope (same as from skills_search). Example: "@official/calculator"',
+                        },
+                        version: {
+                            type: 'string',
+                            description: 'Optional. Skill version. Example: "1.0.0". If omitted, feedback applies to latest version.',
+                        },
+                        type: {
+                            type: 'string',
+                            enum: ['success', 'failure', 'suggestion', 'bug'],
+                            description: 'REQUIRED. Feedback type: "success" (worked well), "failure" (didn\'t work), "suggestion" (improvement idea), "bug" (found a bug)',
+                        },
+                        rating: {
+                            type: 'number',
+                            minimum: 1,
+                            maximum: 5,
+                            description: 'REQUIRED. Rating from 1-5 stars: 1=very poor, 2=poor, 3=average, 4=good, 5=excellent',
+                        },
+                        comment: {
+                            type: 'string',
+                            description: 'Optional. Detailed comment or suggestion to help the author understand specific issues or improvement directions.',
+                        },
+                    },
+                    required: ['name', 'type', 'rating'],
+                },
+            },
+            {
+                name: 'skills_list_cached',
+                description: 'List locally cached skills: Show all skills downloaded to local cache with cache time, usage count, and other metadata. Useful for managing local storage.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {},
+                },
+            },
+            {
+                name: 'skills_publish',
+                description: `Publish skill to hub: Upload a locally developed skill to Open Skills Hub, making it searchable and usable by others.
+
+⚠️ RECOMMENDED METHOD: Use Shell tool to call CLI directly - more stable and faster:
+  cd /Users/george/Documents/AI项目/SkillsHub && node packages/cli/dist/index.js publish <path> -s <scope> -a <author> -v <version> -y
+
+Example:
+  node packages/cli/dist/index.js publish "/Users/george/my-skills/calculator" -s @user -a "George" -v 1.0.0 -y
+
+Arguments:
+  <path>: Skill directory path (required)
+  -s, --scope: Namespace (optional), e.g., @user, @official
+  -a, --author: Author name (required if not in frontmatter)
+  -v, --version: Version number (optional), e.g., 1.0.0
+  -y, --yes: Skip confirmation prompt
+
+If you must use this MCP tool (not recommended), the directory must contain a SKILL.md file with "author" in frontmatter.`,
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        path: {
+                            type: 'string',
+                            description: 'REQUIRED. Absolute path to skill directory containing SKILL.md. Examples: "/Users/george/my-skills/calculator", "/tmp/my-new-skill"',
+                        },
+                        scope: {
+                            type: 'string',
+                            description: 'Optional. Namespace/scope for organizing skills and identifying ownership. Examples: "@user" (personal), "@official" (official), "@myorg" (organization). The @ prefix is optional.',
+                        },
+                        author: {
+                            type: 'string',
+                            description: 'REQUIRED (if not in frontmatter). Author name or organization. Examples: "George", "SkillsHub Team", "@mycompany". Will be saved as ownerId.',
+                        },
+                        version: {
+                            type: 'string',
+                            description: 'Optional. Semantic version number (e.g., "1.0.0"). If omitted, auto-increments patch version for updates, or defaults to "1.0.0" for new skills.',
+                        },
+                    },
+                    required: ['path'],
+                },
+            },
+            {
+                name: 'skills_install',
+                description: 'Install skill to project: Download a skill from the hub and install it to a directory. Automatically detects the platform (Cursor, Codex, CodeBuddy, etc.) and uses appropriate default directory, or you can specify a custom path. Creates the skill folder with SKILL.md and all attachments (scripts, configs, docs, etc.). Directories are created automatically if they don\'t exist.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        name: {
+                            type: 'string',
+                            description: 'REQUIRED. Full skill name (use the "Name" field from skills_search results, NOT "skillId"). Valid formats: "calculator", "@user/calculator", "@official/xlsx".',
+                        },
+                        targetDir: {
+                            type: 'string',
+                            description: 'Optional. Absolute path to PARENT directory (NOT including skill name). System will create a subdirectory named after the skill. Example: use "/path/to/skills" NOT "/path/to/skills/xlsx". If omitted, uses platform defaults: Cursor (~/.cursor/skills), Codex (~/.codex/skills), CodeBuddy (~/.codebuddy/skills).',
+                        },
+                        platform: {
+                            type: 'string',
+                            enum: ['cursor', 'codex', 'codebuddy', 'claude', 'anthropic'],
+                            description: 'Optional. Specify target platform to use its default directory. If omitted, platform is auto-detected. Examples: "cursor", "codex", "codebuddy"',
+                        },
+                        version: {
+                            type: 'string',
+                            description: 'Optional. Specific version to install in semver format. Examples: "1.0.0", "2.1.3". If omitted, installs latest version.',
+                        },
+                    },
+                    required: ['name'],
+                },
+            },
+        ],
+    }));
+    // Handle tool calls
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name: toolName, arguments: args } = request.params;
+        try {
+            switch (toolName) {
+                case 'skills_search':
+                    return await handleSearch(storage, args);
+                case 'skills_get':
+                    return await handleGet(storage, args);
+                case 'skills_scan':
+                    return await handleScan(args);
+                case 'skills_feedback':
+                    return await handleFeedback(storage, queueProcessor, args);
+                case 'skills_list_cached':
+                    return await handleListCached(storage);
+                case 'skills_publish':
+                    return await handlePublish(storage, config, args);
+                case 'skills_install':
+                    return await handleInstall(storage, args);
+                default:
+                    throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${toolName}`);
+            }
+        }
+        catch (error) {
+            if (error instanceof McpError)
+                throw error;
+            logger.error('Tool call error', { toolName, error });
+            throw new McpError(ErrorCode.InternalError, error instanceof Error ? error.message : 'Unknown error');
+        }
+    });
+    return server;
+}
+// ============================================================================
+// Tool Handlers
+// ============================================================================
+//
+// Each tool handler is responsible for:
+// 1. Validating input parameters
+// 2. Executing the requested operation
+// 3. Formatting the response in MCP format
+// 4. Providing clear error messages for AI agents
+//
+// All handlers throw McpError with appropriate error codes for failures.
+// ============================================================================
+// ============================================================================
+// Platform Detection and Default Directories
+// ============================================================================
+//
+// Different AI platforms store skills in different locations. This section
+// provides platform detection and default directory resolution to improve
+// the installation experience across platforms.
+// ============================================================================
+/**
+ * Platform-specific default skills directories
+ * Used when targetDir is not explicitly provided
+ */
+const PLATFORM_SKILLS_DIRS = {
+    cursor: '~/.cursor/skills',
+    codex: '~/.codex/skills',
+    codebuddy: '~/.codebuddy/skills',
+    claude: '~/.claude/skills',
+    anthropic: '~/.anthropic/skills',
+};
+/**
+ * Detect current platform based on multiple signals
+ * Priority: 0. CLI argument, 1. Process info, 2. Environment variables, 3. Directory timestamps, 4. Existing directories
+ * @returns Platform name or 'unknown'
+ */
+function detectPlatform() {
+    // PRIORITY 0: Use CLI-specified platform if provided
+    if (CLI_PLATFORM) {
+        logger.info(`Using CLI-specified platform: ${CLI_PLATFORM}`);
+        return CLI_PLATFORM;
+    }
+    const homeDir = process.env.HOME || process.env.USERPROFILE || '~';
+    // PRIORITY 1: Check parent process and application path
+    try {
+        const { execSync } = require('child_process');
+        const ppid = process.ppid;
+        if (ppid) {
+            // Check process name
+            const parentCmd = execSync(`ps -p ${ppid} -o comm=`, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'ignore'] }).trim().toLowerCase();
+            if (parentCmd.includes('cursor'))
+                return 'cursor';
+            if (parentCmd.includes('codebuddy'))
+                return 'codebuddy';
+            if (parentCmd.includes('codex'))
+                return 'codex';
+            if (parentCmd.includes('claude'))
+                return 'claude';
+            // Check full command/path (for apps that don't show name in comm)
+            try {
+                const fullArgs = execSync(`ps -p ${ppid} -o args=`, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'ignore'] }).trim().toLowerCase();
+                if (fullArgs.includes('codebuddy'))
+                    return 'codebuddy';
+                if (fullArgs.includes('cursor'))
+                    return 'cursor';
+                if (fullArgs.includes('codex'))
+                    return 'codex';
+            }
+            catch (e2) {
+                // Ignore
+            }
+        }
+    }
+    catch (e) {
+        // Process detection failed, continue with other methods
+    }
+    // PRIORITY 2: Check environment variables and working directory
+    if (process.env.CURSOR_USER_DATA || process.env.CURSOR_AGENT)
+        return 'cursor';
+    if (process.env.CODEX_HOME)
+        return 'codex';
+    if (process.env.CODEBUDDY_HOME)
+        return 'codebuddy';
+    // Check if process was launched from CodeBuddy's Application Support
+    try {
+        const cwd = process.cwd();
+        if (cwd.includes('CodeBuddy'))
+            return 'codebuddy';
+        if (cwd.includes('Cursor'))
+            return 'cursor';
+    }
+    catch (e) {
+        // Ignore
+    }
+    // PRIORITY 3: Check most recently modified skills directory (user is likely using this platform)
+    try {
+        let latestPlatform = '';
+        let latestTime = 0;
+        for (const [platform, dir] of Object.entries(PLATFORM_SKILLS_DIRS)) {
+            const expandedDir = dir.replace('~', homeDir);
+            if (fs.existsSync(expandedDir)) {
+                const stats = fs.statSync(expandedDir);
+                if (stats.mtimeMs > latestTime) {
+                    latestTime = stats.mtimeMs;
+                    latestPlatform = platform;
+                }
+            }
+        }
+        if (latestPlatform) {
+            return latestPlatform;
+        }
+    }
+    catch (e) {
+        // Timestamp check failed, continue with simple existence check
+    }
+    // PRIORITY 4: Check for platform-specific directories in preferred order (fallback)
+    const priorityOrder = ['cursor', 'codex', 'codebuddy', 'claude', 'anthropic'];
+    for (const platform of priorityOrder) {
+        const dir = PLATFORM_SKILLS_DIRS[platform];
+        if (dir) {
+            const expandedDir = dir.replace('~', homeDir);
+            if (fs.existsSync(expandedDir)) {
+                return platform;
+            }
+        }
+    }
+    return 'unknown';
+}
+/**
+ * Get default skills directory for a platform
+ * Priority: 1. Project directory, 2. User home directory
+ * @param platform Platform name (optional, auto-detected if not provided)
+ * @returns Expanded absolute path to skills directory
+ */
+function getDefaultSkillsDir(platform) {
+    const homeDir = process.env.HOME || process.env.USERPROFILE || '~';
+    const detectedPlatform = platform || detectPlatform();
+    // PRIORITY 1: Check if we should use project directory
+    try {
+        const cwd = process.cwd();
+        // Check if current directory is not the home directory or system directory
+        const isProjectDir = cwd !== homeDir &&
+            !cwd.startsWith('/usr') &&
+            !cwd.startsWith('/opt') &&
+            !cwd.startsWith('/System') &&
+            !cwd.includes('/Library/Application Support');
+        if (isProjectDir) {
+            // Use project-local skills directory based on platform
+            const platformDir = `.${detectedPlatform}/skills`;
+            const projectSkillsDir = path.join(cwd, platformDir);
+            logger.info(`Using project directory for skills: ${projectSkillsDir}`);
+            return projectSkillsDir;
+        }
+    }
+    catch (e) {
+        logger.warn('Failed to detect project directory, falling back to user home', { error: e });
+    }
+    // PRIORITY 2: Use user home directory (original behavior)
+    const defaultDir = PLATFORM_SKILLS_DIRS[detectedPlatform];
+    if (defaultDir) {
+        return defaultDir.replace('~', homeDir);
+    }
+    // Fallback to generic location
+    return path.join(homeDir, '.skills');
+}
+// ============================================================================
+// File Processing Constants
+// ============================================================================
+// 
+// These constants define which file types are supported for skill publishing
+// and installation. Text files are read and stored as strings, while binary
+// files are stored as base64-encoded data.
+// ============================================================================
+// File extensions and constants for publish/install
+const TEXT_EXTENSIONS = new Set([
+    '.md', '.txt', '.py', '.js', '.ts', '.sh', '.bash', '.zsh',
+    '.json', '.yaml', '.yml', '.xml', '.xsd', '.html', '.css',
+    '.sql', '.r', '.rb', '.pl', '.lua', '.go', '.rs', '.java',
+    '.c', '.cpp', '.h', '.hpp', '.swift', '.kt', '.scala',
+    '.template', '.tpl', '.cfg', '.conf', '.ini', '.env',
+    '.csv', '.tsv', '.log',
+]);
+const BINARY_EXTENSIONS = new Set([
+    '.ttf', '.otf', '.woff', '.woff2',
+    '.png', '.jpg', '.jpeg', '.gif', '.svg', '.ico', '.webp',
+    '.pdf', '.zip', '.tar', '.gz',
+]);
+const SKIP_DIRS = new Set([
+    'node_modules', '.git', '.svn', '__pycache__', '.DS_Store',
+    'dist', 'build', '.cache', '.vscode', '.idea',
+]);
+const SKIP_FILES = new Set([
+    '.DS_Store', 'Thumbs.db', '.gitignore', '.npmignore',
+]);
+function isTextFile(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    return TEXT_EXTENSIONS.has(ext);
+}
+function isBinaryFile(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    return BINARY_EXTENSIONS.has(ext);
+}
+function shouldIncludeFile(filePath) {
+    const basename = path.basename(filePath);
+    if (SKIP_FILES.has(basename))
+        return false;
+    return isTextFile(filePath) || isBinaryFile(filePath);
+}
+function getMimeType(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    const mimeTypes = {
+        '.ttf': 'font/ttf', '.otf': 'font/otf', '.woff': 'font/woff', '.woff2': 'font/woff2',
+        '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif',
+        '.svg': 'image/svg+xml', '.webp': 'image/webp', '.ico': 'image/x-icon',
+        '.pdf': 'application/pdf', '.zip': 'application/zip',
+    };
+    return mimeTypes[ext] || 'application/octet-stream';
+}
+function parseSkillMdFile(content) {
+    const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+    if (frontmatterMatch && frontmatterMatch[1] && frontmatterMatch[2] !== undefined) {
+        return {
+            frontmatter: parseYaml(frontmatterMatch[1]),
+            markdown: frontmatterMatch[2].trim(),
+        };
+    }
+    return { frontmatter: {}, markdown: content.trim() };
+}
+function collectFiles(dirPath, basePath = dirPath) {
+    const result = { skillMd: null, files: [], totalSize: 0 };
+    if (!dirPath || !fs.existsSync(dirPath))
+        return result;
+    const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+    for (const entry of entries) {
+        const fullPath = path.join(dirPath, entry.name);
+        const relativePath = path.relative(basePath, fullPath);
+        if (entry.isDirectory()) {
+            if (SKIP_DIRS.has(entry.name))
+                continue;
+            const subResult = collectFiles(fullPath, basePath);
+            result.files.push(...subResult.files);
+            result.totalSize += subResult.totalSize;
+            if (subResult.skillMd && !result.skillMd) {
+                result.skillMd = subResult.skillMd;
+            }
+        }
+        else if (entry.isFile()) {
+            if (entry.name.toUpperCase() === 'SKILL.MD') {
+                const content = fs.readFileSync(fullPath, 'utf-8');
+                result.skillMd = { path: relativePath, content };
+                result.totalSize += content.length;
+                continue;
+            }
+            if (!shouldIncludeFile(entry.name))
+                continue;
+            const stat = fs.statSync(fullPath);
+            if (stat.size > 10 * 1024 * 1024)
+                continue; // Skip >10MB
+            let content;
+            if (isTextFile(fullPath)) {
+                content = fs.readFileSync(fullPath, 'utf-8');
+            }
+            else if (isBinaryFile(fullPath)) {
+                const buffer = fs.readFileSync(fullPath);
+                content = `data:${getMimeType(fullPath)};base64,${buffer.toString('base64')}`;
+            }
+            else {
+                continue;
+            }
+            result.files.push({ path: relativePath, content, size: stat.size });
+            result.totalSize += stat.size;
+        }
+    }
+    return result;
+}
+/**
+ * Handle skills_search tool call
+ *
+ * Searches the Open Skills Hub by keywords, category, or author.
+ * Returns a formatted list of matching skills with key metadata.
+ *
+ * @param storage - Storage interface for database operations
+ * @param args - Search parameters (query, category, author, limit)
+ * @returns MCP response with formatted skill list
+ */
+async function handleSearch(storage, args) {
+    const result = await storage.searchSkills({
+        query: args['query'],
+        category: args['category'],
+        author: args['author'],
+        limit: args['limit'] ?? 10,
+    });
+    const text = result.items.length === 0
+        ? 'No skills found matching your query.'
+        : `Found ${result.items.length} skill(s):\n\n` + result.items.map((skill, index) => `${index + 1}. **Name:** ${skill.fullName}\n   **Author:** ${skill.ownerId ?? 'unknown'}\n   **Version:** ${skill.latestVersion}\n   **Description:** ${skill.description.substring(0, 120)}${skill.description.length > 120 ? '...' : ''}\n   **Security:** ${skill.securityLevel ?? 'unknown'} (${skill.securityScore ?? 'N/A'}) | **Uses:** ${skill.stats.totalUses}`).join('\n\n') +
+            `\n\n💡 To install a skill, use: skills_install with the "name" parameter (e.g., {"name": "${result.items[0]?.fullName}"})`;
+    return {
+        content: [{ type: 'text', text }],
+    };
+}
+/**
+ * Handle skills_get tool call
+ *
+ * Retrieves complete skill content including SKILL.md, attachments, metadata,
+ * and version information. Results are cached locally for offline access.
+ *
+ * @param storage - Storage interface for database operations
+ * @param args - Parameters (name: required, version: optional)
+ * @returns MCP response with complete skill content
+ * @throws McpError if skill name is missing or skill not found
+ */
+async function handleGet(storage, args) {
+    const name = args['name'];
+    const requestedVersion = args['version'];
+    // Parse name
+    const { scope, name: skillName } = parseSkillFullName(name);
+    const fullName = buildSkillFullName(skillName, scope);
+    // Get skill
+    const skill = await storage.getSkillByName(fullName);
+    if (!skill) {
+        throw new McpError(ErrorCode.InvalidParams, `Skill '${fullName}' not found`);
+    }
+    // Get version
+    let version;
+    if (requestedVersion) {
+        version = await storage.getVersion(skill.id, requestedVersion);
+        if (!version) {
+            throw new McpError(ErrorCode.InvalidParams, `Version '${requestedVersion}' not found for '${fullName}'`);
+        }
+    }
+    else {
+        version = await storage.getLatestVersion(skill.id);
+        if (!version) {
+            throw new McpError(ErrorCode.InvalidParams, `No versions found for '${fullName}'`);
+        }
+    }
+    // Record use
+    await storage.incrementSkillUses(skill.id);
+    await storage.incrementVersionUses(version.id);
+    const useRecord = {
+        id: generateUUID(),
+        skillId: skill.id,
+        versionId: version.id,
+        source: 'mcp',
+        cacheHit: false,
+        ip: '127.0.0.1',
+        createdAt: now(),
+    };
+    await storage.createUseRecord(useRecord);
+    // Build response
+    const content = version.content;
+    const frontmatterLines = Object.entries(content.frontmatter)
+        .filter(([_, v]) => v !== undefined)
+        .map(([k, v]) => {
+        if (Array.isArray(v)) {
+            return `${k}:\n${v.map(item => `  - ${item}`).join('\n')}`;
+        }
+        return `${k}: ${v}`;
+    });
+    const text = `# ${skill.displayName ?? skill.fullName}
+
+## Metadata
+- **Name:** ${skill.fullName} (use this in skills_install)
+- **Author:** ${skill.ownerId ?? 'unknown'}
+- **Version:** ${version.version}
+- **Security Level:** ${skill.securityLevel ?? 'unknown'} (Score: ${skill.securityScore ?? 'N/A'})
+- **Uses:** ${skill.stats.totalUses}
+- **Rating:** ${skill.rating.average}/5 (${skill.rating.count} reviews)
+
+## Frontmatter
+\`\`\`yaml
+${frontmatterLines.join('\n')}
+\`\`\`
+
+## Content
+${content.markdown}`;
+    return {
+        content: [{ type: 'text', text }],
+    };
+}
+/**
+ * Handle skills_scan tool call
+ *
+ * Performs security scanning on skill content using SkillsGuard with 16 built-in
+ * security rules. Returns a score (0-100) and detailed issue report.
+ *
+ * @param args - Parameters (content: required text to scan)
+ * @returns MCP response with security scan results
+ */
+async function handleScan(args) {
+    const content = args['content'];
+    const scanner = getScanner();
+    const result = await scanner.scan(content);
+    const issuesText = result.issues.length === 0
+        ? 'No security issues found.'
+        : result.issues.map(issue => `[${issue.severity.toUpperCase()}] ${issue.ruleName} (${issue.ruleId})\n  Line ${issue.line}: ${issue.content}\n  ${issue.message}\n  Suggestion: ${issue.suggestion ?? 'N/A'}`).join('\n\n');
+    const text = `## Security Scan Results
+
+**Score:** ${result.summary.score}/100
+**Level:** ${result.summary.level.toUpperCase()}
+
+### Issue Summary
+- High: ${result.summary.issueCount.high}
+- Medium: ${result.summary.issueCount.medium}
+- Low: ${result.summary.issueCount.low}
+
+### Issues
+${issuesText}
+
+### Recommendations
+${result.summary.recommendations.map(r => `• ${r}`).join('\n')}`;
+    return {
+        content: [{ type: 'text', text }],
+    };
+}
+/**
+ * Handle skills_feedback tool call
+ *
+ * Submits feedback for a skill (success, failure, suggestion, or bug report).
+ * Feedback is queued locally and processed asynchronously with auto-retry.
+ *
+ * @param storage - Storage interface for database operations
+ * @param queueProcessor - Queue processor for async feedback handling
+ * @param args - Parameters (name, type, rating: required; version, comment: optional)
+ * @returns MCP response confirming feedback submission
+ * @throws McpError if required parameters are missing or invalid
+ */
+async function handleFeedback(storage, queueProcessor, args) {
+    const name = args['name'];
+    const feedbackType = args['type'];
+    const rating = args['rating'];
+    const comment = args['comment'];
+    const requestedVersion = args['version'];
+    // Parse name
+    const { scope, name: skillName } = parseSkillFullName(name);
+    const fullName = buildSkillFullName(skillName, scope);
+    // Get skill
+    const skill = await storage.getSkillByName(fullName);
+    if (!skill) {
+        throw new McpError(ErrorCode.InvalidParams, `Skill '${fullName}' not found`);
+    }
+    // Get version
+    let version;
+    if (requestedVersion) {
+        version = await storage.getVersion(skill.id, requestedVersion);
+    }
+    else {
+        version = await storage.getLatestVersion(skill.id);
+    }
+    if (!version) {
+        throw new McpError(ErrorCode.InvalidParams, 'Skill version not found');
+    }
+    // Create feedback
+    const feedback = {
+        id: generateUUID(),
+        skillId: skill.id,
+        skillVersion: version.version,
+        feedbackType,
+        rating,
+        comment,
+        context: {},
+        status: 'pending',
+        createdAt: now(),
+    };
+    try {
+        await storage.createFeedback(feedback);
+        // Update skill rating
+        const feedbacks = await storage.getFeedbacks(skill.id, { limit: 1000 });
+        const ratings = feedbacks.items.map(f => f.rating).filter((r) => r !== undefined);
+        const averageRating = ratings.length > 0
+            ? ratings.reduce((sum, r) => sum + r, 0) / ratings.length
+            : 0;
+        await storage.updateSkill(skill.id, {
+            rating: {
+                average: Math.round(averageRating * 10) / 10,
+                count: ratings.length,
+            },
+        });
+    }
+    catch (error) {
+        // Queue for retry if failed
+        const queueItem = {
+            id: generateUUID(),
+            skillName: fullName,
+            skillVersion: version.version,
+            feedback: {
+                type: feedbackType,
+                rating,
+                comment,
+                context: {},
+            },
+            status: 'pending',
+            attempts: 0,
+            maxAttempts: 5,
+            baseDelay: 1000,
+            currentDelay: 1000,
+            maxDelay: 3600000,
+            createdAt: now(),
+        };
+        await queueProcessor.enqueue(queueItem);
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Feedback queued for ${fullName}@${version.version}. Will be submitted when connection is restored.`,
+                }],
+        };
+    }
+    return {
+        content: [{
+                type: 'text',
+                text: `## ✅ Feedback Submitted Successfully!
+
+**Name:** ${fullName}
+**Version:** ${version.version}
+**Type:** ${feedbackType}
+**Rating:** ${'⭐'.repeat(rating)} (${rating}/5)${comment ? `\n**Comment:** ${comment}` : ''}
+
+Thank you for helping improve this skill!`,
+            }],
+    };
+}
+/**
+ * Handle skills_list_cached tool call
+ *
+ * Lists all skills currently stored in the local cache with metadata
+ * including cache time, usage count, and size.
+ *
+ * @param storage - Storage interface for database operations
+ * @returns MCP response with formatted list of cached skills
+ */
+async function handleListCached(storage) {
+    const cacheEntries = await storage.getAllCacheMetadata();
+    if (cacheEntries.length === 0) {
+        return {
+            content: [{ type: 'text', text: 'No skills currently cached locally.' }],
+        };
+    }
+    const text = `## Cached Skills (${cacheEntries.length})
+
+${cacheEntries.map((entry, index) => `${index + 1}. **Name:** ${entry.skillName}\n   **Version:** ${entry.version}\n   **Cached:** ${entry.cachedAt.split('T')[0]}\n   **Hits:** ${entry.hitCount}`).join('\n\n')}
+
+💡 Use skills_install with the "name" parameter to reinstall or update a cached skill.`;
+    return {
+        content: [{ type: 'text', text }],
+    };
+}
+/**
+ * Handle skills_publish tool call
+ *
+ * Publishes a skill to the hub by spawning the CLI tool as a subprocess.
+ * This approach is more stable than the direct implementation. The skill directory
+ * must contain a SKILL.md file. Automatically performs security scanning.
+ *
+ * @param storage - Storage interface for database operations
+ * @param config - Configuration instance for API URL
+ * @param args - Parameters (path: required; scope, version: optional)
+ * @returns MCP response with publish confirmation
+ * @throws McpError if path is missing, invalid, or publish fails
+ */
+async function handlePublish(storage, config, args) {
+    const inputPath = args['path'];
+    const scopeArg = args['scope'];
+    const authorArg = args['author'];
+    const versionArg = args['version'];
+    if (!inputPath) {
+        throw new McpError(ErrorCode.InvalidParams, 'Path is required');
+    }
+    const resolvedPath = path.resolve(inputPath);
+    if (!fs.existsSync(resolvedPath)) {
+        throw new McpError(ErrorCode.InvalidParams, `Path not found: ${resolvedPath}`);
+    }
+    const stat = fs.statSync(resolvedPath);
+    if (!stat.isDirectory()) {
+        throw new McpError(ErrorCode.InvalidParams, 'Path must be a directory containing SKILL.md');
+    }
+    // Check if SKILL.md exists
+    const skillMdPath = path.join(resolvedPath, 'SKILL.md');
+    if (!fs.existsSync(skillMdPath)) {
+        throw new McpError(ErrorCode.InvalidParams, `SKILL.md not found in ${resolvedPath}`);
+    }
+    // Check if author is provided (either as arg or in frontmatter)
+    if (!authorArg) {
+        const skillMdContent = fs.readFileSync(skillMdPath, 'utf-8');
+        const parsed = parseSkillMdFile(skillMdContent);
+        const frontmatterAuthor = parsed.frontmatter['author']
+            ?? parsed.frontmatter['metadata']?.['author'];
+        if (!frontmatterAuthor) {
+            throw new McpError(ErrorCode.InvalidParams, 'Author is required! Provide via --author argument or add "author: Your Name" to SKILL.md frontmatter.');
+        }
+    }
+    // Build CLI command options
+    const commands = buildPublishCliCommands(resolvedPath, scopeArg, authorArg, versionArg);
+    // Return instructions for the agent
+    const text = `## 📦 如何发布 Skill
+
+请使用 Shell 工具执行以下 CLI 命令来发布 skill（按优先级排序）：
+
+### 方式 1：使用全局安装的 CLI（推荐）
+如果已通过 \`npm link\` 或 \`npm install -g\` 安装：
+
+\`\`\`bash
+${commands.global}
+\`\`\`
+
+### 方式 2：使用 npx（无需安装，发布到 npm 后可用）
+\`\`\`bash
+${commands.npx}
+\`\`\`
+
+### 方式 3：使用本地项目路径（开发模式）
+如果有 SkillsHub 项目：
+
+\`\`\`bash
+${commands.local}
+\`\`\`
+
+---
+
+### 命令说明：
+- **路径**: ${resolvedPath}
+${scopeArg ? `- **作用域**: ${scopeArg}` : '- **作用域**: 未指定（将使用默认）'}
+${authorArg ? `- **作者**: ${authorArg}` : '- **作者**: 将从 SKILL.md frontmatter 读取'}
+${versionArg ? `- **版本**: ${versionArg}` : '- **版本**: 未指定（将自动递增）'}
+
+### 执行步骤：
+1. 尝试方式 1，如果失败则尝试方式 2 或 3
+2. 等待命令完成（通常需要 1-3 秒）
+3. 检查输出确认发布成功
+4. 如需在 Web UI 查看，执行: \`curl -X POST http://localhost:3001/reload\`
+
+### 注意事项：
+- 确保目录包含有效的 SKILL.md 文件
+- 如果版本已存在，命令会失败并提示
+- 发布成功后会自动进行安全扫描（评分 0-100）`;
+    return {
+        content: [{ type: 'text', text }],
+    };
+}
+/**
+ * Build CLI commands for publishing a skill (multiple options)
+ */
+function buildPublishCliCommands(skillPath, scope, author, version) {
+    // Build argument list
+    const args = ['publish', `"${skillPath}"`];
+    if (scope) {
+        args.push('-s', scope);
+    }
+    if (author) {
+        args.push('-a', `"${author}"`);
+    }
+    if (version) {
+        args.push('-v', version);
+    }
+    args.push('-y'); // Skip confirmation
+    const argsStr = args.join(' ');
+    // Calculate local path for development
+    const mcpServerDir = path.dirname(decodeURIComponent(new URL(import.meta.url).pathname));
+    const projectRoot = path.resolve(mcpServerDir, '../../..'); // Go up to project root
+    const cliPath = path.join(projectRoot, 'packages/cli/dist/index.js');
+    return {
+        global: `skills ${argsStr}`,
+        npx: `npx open-skills-hub ${argsStr}`,
+        local: `node "${cliPath}" ${argsStr}`,
+    };
+}
+/**
+ * Publish skill via CLI tool to avoid database concurrency issues
+ */
+async function handlePublishViaCli(skillPath, scope, version, config) {
+    const { spawn } = await import('child_process');
+    // Build CLI command - use absolute path from environment or relative to this file
+    // The MCP server is in packages/mcp-server/dist/index.js
+    // The CLI is in packages/cli/dist/index.js
+    const mcpServerDir = path.dirname(decodeURIComponent(new URL(import.meta.url).pathname));
+    const projectRoot = path.resolve(mcpServerDir, '../../..'); // Go up to project root
+    const cliPath = path.join(projectRoot, 'packages/cli/dist/index.js');
+    // Verify CLI exists
+    if (!fs.existsSync(cliPath)) {
+        logger.error('CLI tool not found', { cliPath, projectRoot, mcpServerDir });
+        throw new McpError(ErrorCode.InternalError, `CLI tool not found at ${cliPath}. Please ensure the CLI is built.`);
+    }
+    logger.info('Using CLI tool for publish', { cliPath, skillPath, scope, version });
+    const args = ['publish', skillPath];
+    if (scope) {
+        args.push('-s', scope);
+    }
+    if (version) {
+        args.push('-v', version);
+    }
+    args.push('-y'); // Auto-confirm
+    return new Promise((resolve, reject) => {
+        const child = spawn('node', [cliPath, ...args], {
+            env: {
+                ...process.env,
+                STORAGE_PATH: config.get().storagePath,
+                STORAGE_MODE: config.get().mode,
+                SKILLS_REGISTRY_URL: config.get().apiUrl || 'http://localhost:3001',
+            },
+            cwd: projectRoot, // Use project root as working directory
+        });
+        let stdout = '';
+        let stderr = '';
+        if (child.stdout) {
+            child.stdout.on('data', (data) => {
+                stdout += data.toString();
+            });
+        }
+        if (child.stderr) {
+            child.stderr.on('data', (data) => {
+                stderr += data.toString();
+            });
+        }
+        child.on('close', async (code) => {
+            if (code === 0) {
+                // Extract skill name and version from stdout
+                const nameMatch = stdout.match(/Name:\s+(@?[\w-]+\/[\w-]+)/);
+                const versionMatch = stdout.match(/Version:\s+([\d.]+)/);
+                const actionMatch = stdout.match(/Action:\s+(.+)/);
+                const skillName = nameMatch?.[1] || 'unknown';
+                const skillVersion = versionMatch?.[1] || 'unknown';
+                const action = actionMatch?.[1]?.trim() || 'Published';
+                // Trigger API reload
+                const apiUrl = config.get().apiUrl || 'http://localhost:3001';
+                await reloadApi(apiUrl);
+                const resultText = `## ✅ Published Successfully via MCP!
+
+**Skill:** ${skillName}
+**Version:** ${skillVersion}
+**Action:** ${action}
+
+The skill has been published and the API has been reloaded.
+You can now use it with \`skills_get\` or view it at http://localhost:8080
+
+---
+Use \`skills_get ${skillName}\` to retrieve this skill.`;
+                resolve({
+                    content: [{ type: 'text', text: resultText }],
+                });
+            }
+            else {
+                // Extract error message from stderr or stdout
+                const errorMsg = stderr || stdout || `CLI exited with code ${code}`;
+                logger.error('CLI publish failed', { code, stderr, stdout });
+                reject(new McpError(ErrorCode.InternalError, `Failed to publish skill: ${errorMsg}`));
+            }
+        });
+        child.on('error', (error) => {
+            logger.error('Failed to spawn CLI process', { error });
+            reject(new McpError(ErrorCode.InternalError, `Failed to spawn CLI process: ${error.message}`));
+        });
+    });
+}
+async function handlePublishOld(storage, config, args) {
+    const inputPath = args['path'];
+    const scopeArg = args['scope'];
+    const versionArg = args['version'];
+    if (!inputPath) {
+        throw new McpError(ErrorCode.InvalidParams, 'Path is required');
+    }
+    const resolvedPath = path.resolve(inputPath);
+    if (!fs.existsSync(resolvedPath)) {
+        throw new McpError(ErrorCode.InvalidParams, `Path not found: ${resolvedPath}`);
+    }
+    const stat = fs.statSync(resolvedPath);
+    if (!stat.isDirectory()) {
+        throw new McpError(ErrorCode.InvalidParams, 'Path must be a directory containing SKILL.md');
+    }
+    // Collect files
+    const collected = collectFiles(resolvedPath);
+    if (!collected.skillMd) {
+        throw new McpError(ErrorCode.InvalidParams, 'SKILL.md not found in directory');
+    }
+    // Parse SKILL.md
+    const parsed = parseSkillMdFile(collected.skillMd.content);
+    const skillDirName = path.basename(resolvedPath);
+    const skillName = parsed.frontmatter['name'] ?? skillDirName;
+    if (!isValidSkillName(skillName)) {
+        throw new McpError(ErrorCode.InvalidParams, `Invalid skill name: ${skillName}. Use lowercase letters, numbers, and hyphens.`);
+    }
+    const scope = scopeArg?.replace(/^@/, '');
+    const fullName = buildSkillFullName(skillName, scope);
+    // Check existing skill
+    const existingSkill = await storage.getSkillByName(fullName);
+    const isUpdate = !!existingSkill;
+    // Determine version
+    let version = versionArg ?? parsed.frontmatter['version'];
+    if (!version) {
+        if (isUpdate) {
+            const [major, minor, patch] = existingSkill.latestVersion.split('.').map(Number);
+            version = `${major}.${minor}.${(patch ?? 0) + 1}`;
+        }
+        else {
+            version = '1.0.0';
+        }
+    }
+    if (!isValidSemver(version)) {
+        throw new McpError(ErrorCode.InvalidParams, `Invalid version: ${version}. Use semantic versioning (e.g., 1.0.0).`);
+    }
+    // Check version doesn't exist
+    if (isUpdate) {
+        const existingVersion = await storage.getVersion(existingSkill.id, version);
+        if (existingVersion) {
+            logger.warn(`Version ${version} already exists for ${fullName}`);
+            throw new McpError(ErrorCode.InvalidParams, `Version ${version} already exists for ${fullName}.`);
+        }
+        logger.info(`Creating new version ${version} for existing skill ${fullName}`);
+    }
+    else {
+        logger.info(`Creating new skill ${fullName} with version ${version}`);
+    }
+    // Security scan
+    const scanner = getScanner();
+    const scanResult = await scanner.scan(collected.skillMd.content);
+    for (const file of collected.files) {
+        if (file.path.startsWith('scripts/') && (file.path.endsWith('.py') || file.path.endsWith('.sh') || file.path.endsWith('.js'))) {
+            const fileScanResult = await scanner.scan(file.content);
+            if (fileScanResult && fileScanResult.issues) {
+                scanResult.issues.push(...fileScanResult.issues);
+            }
+            if (fileScanResult && fileScanResult.summary) {
+                scanResult.summary.score = Math.min(scanResult.summary.score, fileScanResult.summary.score);
+            }
+        }
+    }
+    // Build skill content
+    const skillContent = {
+        frontmatter: {
+            name: skillName,
+            description: parsed.frontmatter['description'] ?? '',
+            allowedTools: parsed.frontmatter['allowedTools'],
+            argumentHint: parsed.frontmatter['argumentHint'],
+            disableModelInvocation: parsed.frontmatter['disableModelInvocation'],
+            userInvocable: parsed.frontmatter['userInvocable'],
+            model: parsed.frontmatter['model'],
+            license: parsed.frontmatter['license'],
+            compatibility: parsed.frontmatter['compatibility'],
+            metadata: parsed.frontmatter['metadata'],
+        },
+        markdown: parsed.markdown,
+        files: collected.files.length > 0 ? collected.files : undefined,
+    };
+    const contentString = JSON.stringify(skillContent);
+    const contentHash = sha256(contentString);
+    const timestamp = now();
+    const versionId = generateUUID();
+    if (isUpdate) {
+        // Create new version
+        const versionRecord = {
+            id: versionId,
+            skillId: existingSkill.id,
+            version,
+            tag: 'latest',
+            content: skillContent,
+            packageUrl: `local://${fullName}/${version}`,
+            packageSize: contentString.length,
+            packageHash: contentHash,
+            status: 'published',
+            uses: 0,
+            createdAt: timestamp,
+            publishedAt: timestamp,
+        };
+        await storage.createVersion(versionRecord);
+        logger.info(`Version ${version} created for skill ${fullName}`);
+        // Update previous latest tag
+        const versions = await storage.getVersions(existingSkill.id, { limit: 100 });
+        for (const v of versions.items) {
+            if (v.id !== versionId && v.tag === 'latest') {
+                await storage.updateVersion(v.id, { tag: undefined });
+            }
+        }
+        // Update skill
+        await storage.updateSkill(existingSkill.id, {
+            latestVersion: version,
+            latestVersionId: versionId,
+            securityScore: scanResult.summary.score,
+            securityLevel: scanResult.summary.level,
+            stats: {
+                ...existingSkill.stats,
+                versionCount: existingSkill.stats.versionCount + 1,
+            },
+        });
+        logger.info(`Skill ${fullName} updated to version ${version}`);
+    }
+    else {
+        // Create new skill
+        const skillId = generateUUID();
+        const skillRecord = {
+            id: skillId,
+            name: skillName,
+            scope,
+            fullName,
+            displayName: parsed.frontmatter['displayName'],
+            description: parsed.frontmatter['description'] ?? '',
+            keywords: [],
+            visibility: 'public',
+            status: 'active',
+            latestVersion: version,
+            latestVersionId: versionId,
+            ownerType: 'user',
+            securityScore: scanResult.summary.score,
+            securityLevel: scanResult.summary.level,
+            stats: { totalUses: 0, weeklyUses: 0, monthlyUses: 0, versionCount: 1, derivationCount: 0 },
+            rating: { average: 0, count: 0 },
+            createdAt: timestamp,
+            updatedAt: timestamp,
+            publishedAt: timestamp,
+        };
+        await storage.createSkill(skillRecord);
+        // Create version
+        const versionRecord = {
+            id: versionId,
+            skillId,
+            version,
+            tag: 'latest',
+            content: skillContent,
+            packageUrl: `local://${fullName}/${version}`,
+            packageSize: contentString.length,
+            packageHash: contentHash,
+            status: 'published',
+            uses: 0,
+            createdAt: timestamp,
+            publishedAt: timestamp,
+        };
+        await storage.createVersion(versionRecord);
+    }
+    // Create audit log
+    const auditLog = {
+        id: generateUUID(),
+        timestamp,
+        eventType: isUpdate ? 'version.published' : 'skill.published',
+        actor: { type: 'user', id: 'mcp-user' },
+        resource: { type: 'skill', name: fullName, version },
+        action: 'publish',
+        result: 'success',
+        details: { filesCount: collected.files.length + 1, totalSize: collected.totalSize },
+    };
+    await storage.createAuditLog(auditLog);
+    logger.info('Audit log created, syncing database...');
+    // Force sync to disk (SQLite is in-memory, need to persist)
+    await storage.sync();
+    logger.info('Database synced to disk');
+    // Reload API to pick up the changes
+    const apiUrl = config.get().apiUrl;
+    if (apiUrl && apiUrl !== 'https://api.open-skills-hub.io') {
+        await reloadApi(apiUrl);
+    }
+    else {
+        // Try local API at default port
+        await reloadApi('http://localhost:3001');
+    }
+    const filesList = collected.files && collected.files.length > 0
+        ? collected.files.map(f => `- ${f.path}`).join('\n')
+        : 'No additional files';
+    const resultText = `## ✅ Published Successfully!
+
+**Skill:** ${fullName}
+**Version:** ${version}
+**Action:** ${isUpdate ? 'New version added' : 'New skill created'}
+
+### Files
+- SKILL.md
+${filesList}
+
+### Security Scan
+- Score: ${scanResult.summary.score}/100
+- Level: ${scanResult.summary.level.toUpperCase()}
+${scanResult.issues.length > 0 ? `- Issues: ${scanResult.issues.length}` : ''}
+
+---
+Use \`skills_get\` to retrieve this skill, or \`skills_install\` to download it to a project.`;
+    return {
+        content: [{ type: 'text', text: resultText }],
+    };
+}
+/**
+ * Handle skills_install tool call
+ *
+ * Downloads a skill from the hub and installs it to a local directory.
+ * Creates the skill folder with SKILL.md and all attachments (scripts, configs, etc.).
+ * The skill name must match exactly as returned from skills_search.
+ *
+ * Supports automatic platform detection and default directory resolution:
+ * - If targetDir is not provided, uses platform-specific default
+ * - If platform is specified, uses that platform's default directory
+ * - Automatically creates directories if they don't exist
+ *
+ * @param storage - Storage interface for database operations
+ * @param args - Parameters (name: required; targetDir, platform, version: optional)
+ * @returns MCP response with installation confirmation
+ * @throws McpError if required parameters are missing, skill not found, or install fails
+ */
+async function handleInstall(storage, args) {
+    const name = args['name'];
+    let targetDir = args['targetDir'];
+    const platform = args['platform'];
+    const requestedVersion = args['version'];
+    if (!name) {
+        throw new McpError(ErrorCode.InvalidParams, 'Skill name is required');
+    }
+    // Auto-detect target directory if not provided
+    let autoDetected = false;
+    let detectedPlatformName = '';
+    if (!targetDir) {
+        detectedPlatformName = platform || detectPlatform();
+        targetDir = getDefaultSkillsDir(platform);
+        autoDetected = true;
+        logger.info(`Auto-detected target directory: ${targetDir}`, { platform: detectedPlatformName });
+    }
+    // Parse name
+    const { scope, name: skillName } = parseSkillFullName(name);
+    const fullName = buildSkillFullName(skillName, scope);
+    // Get skill
+    const skill = await storage.getSkillByName(fullName);
+    if (!skill) {
+        throw new McpError(ErrorCode.InvalidParams, `Skill '${fullName}' not found`);
+    }
+    // Get version
+    let version;
+    if (requestedVersion) {
+        version = await storage.getVersion(skill.id, requestedVersion);
+        if (!version) {
+            throw new McpError(ErrorCode.InvalidParams, `Version '${requestedVersion}' not found for '${fullName}'`);
+        }
+    }
+    else {
+        version = await storage.getLatestVersion(skill.id);
+        if (!version) {
+            throw new McpError(ErrorCode.InvalidParams, `No versions found for '${fullName}'`);
+        }
+    }
+    // Resolve target directory
+    const resolvedTargetDir = path.resolve(targetDir);
+    const skillDir = path.join(resolvedTargetDir, skillName);
+    // Create directories
+    if (!fs.existsSync(resolvedTargetDir)) {
+        fs.mkdirSync(resolvedTargetDir, { recursive: true });
+    }
+    if (!fs.existsSync(skillDir)) {
+        fs.mkdirSync(skillDir, { recursive: true });
+    }
+    const content = version.content;
+    const installedFiles = [];
+    // Write SKILL.md
+    const frontmatterLines = Object.entries(content.frontmatter)
+        .filter(([_, v]) => v !== undefined && v !== null)
+        .map(([k, v]) => {
+        if (Array.isArray(v)) {
+            return `${k}:\n${v.map(item => `  - ${item}`).join('\n')}`;
+        }
+        if (typeof v === 'object') {
+            return `${k}:\n${Object.entries(v).map(([k2, v2]) => `  ${k2}: ${v2}`).join('\n')}`;
+        }
+        return `${k}: ${v}`;
+    });
+    const skillMdContent = `---
+${frontmatterLines.join('\n')}
+---
+
+${content.markdown}`;
+    const skillMdPath = path.join(skillDir, 'SKILL.md');
+    fs.writeFileSync(skillMdPath, skillMdContent, 'utf-8');
+    installedFiles.push('SKILL.md');
+    // Write additional files
+    if (content.files && content.files.length > 0) {
+        for (const file of content.files) {
+            const filePath = path.join(skillDir, file.path);
+            const fileDir = path.dirname(filePath);
+            // Create subdirectories if needed
+            if (!fs.existsSync(fileDir)) {
+                fs.mkdirSync(fileDir, { recursive: true });
+            }
+            // Check if it's a base64 encoded binary file
+            if (file.content.startsWith('data:') && file.content.includes(';base64,')) {
+                const base64Data = file.content.split(';base64,')[1] ?? '';
+                const buffer = Buffer.from(base64Data, 'base64');
+                fs.writeFileSync(filePath, buffer);
+            }
+            else {
+                fs.writeFileSync(filePath, file.content, 'utf-8');
+            }
+            installedFiles.push(file.path);
+        }
+    }
+    // Record use
+    await storage.incrementSkillUses(skill.id);
+    await storage.incrementVersionUses(version.id);
+    const useRecord = {
+        id: generateUUID(),
+        skillId: skill.id,
+        versionId: version.id,
+        source: 'mcp',
+        cacheHit: false,
+        ip: '127.0.0.1',
+        createdAt: now(),
+    };
+    await storage.createUseRecord(useRecord);
+    const installedFilesList = installedFiles.length > 0
+        ? installedFiles.map(f => `• ${f}`).join('\n')
+        : 'No files installed';
+    const platformInfo = autoDetected
+        ? `\n**Platform:** ${detectedPlatformName} (auto-detected)\n**Target Directory:** ${resolvedTargetDir} (auto-created)`
+        : `\n**Target Directory:** ${resolvedTargetDir}`;
+    const resultText = `## ✅ Skill Installed Successfully!
+
+**Name:** ${fullName}
+**Version:** ${version.version}${platformInfo}
+**Installation Path:** \`${skillDir}\`
+
+### Files Installed (${installedFiles.length})
+${installedFilesList}
+
+---
+${autoDetected ? '✨ Directory was automatically created for your platform.\n' : ''}The skill is ready to use at: \`${skillDir}\``;
+    return {
+        content: [{ type: 'text', text: resultText }],
+    };
+}
+// ============================================================================
+// Command Line Arguments Parsing
+// ============================================================================
+/**
+ * Parse command line arguments
+ * Supports: --platform=<platform_name>
+ */
+function parseCliArgs() {
+    const args = process.argv.slice(2);
+    const result = {};
+    for (const arg of args) {
+        if (arg.startsWith('--platform=')) {
+            result.platform = arg.split('=')[1];
+        }
+        else if (arg === '--platform' && args[args.indexOf(arg) + 1]) {
+            result.platform = args[args.indexOf(arg) + 1];
+        }
+    }
+    return result;
+}
+// Global variable to store CLI-specified platform
+let CLI_PLATFORM;
+// ============================================================================
+// Main Entry Point
+// ============================================================================
+async function main() {
+    // Parse command line arguments
+    const cliArgs = parseCliArgs();
+    CLI_PLATFORM = cliArgs.platform;
+    if (CLI_PLATFORM) {
+        logger.info(`Starting Open Skills Hub MCP Server with platform override: ${CLI_PLATFORM}`);
+    }
+    else {
+        logger.info('Starting Open Skills Hub MCP Server');
+    }
+    const server = await createMcpServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    logger.info('Open Skills Hub MCP Server started');
+    // Handle shutdown
+    process.on('SIGINT', async () => {
+        logger.info('Shutting down MCP server...');
+        await server.close();
+        process.exit(0);
+    });
+    process.on('SIGTERM', async () => {
+        logger.info('Shutting down MCP server...');
+        await server.close();
+        process.exit(0);
+    });
+}
+main().catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map