open-skills-hub-mcp

Model Context Protocol (MCP) server for SkillsHub - enabling AI agents to discover, publish, and manage reusable skills through a standardized protocol.

Overview

SkillsHub MCP Server acts as a bridge between AI agents and the Open Skills Hub, providing a standardized interface for skill management operations. Think of it as "npm for AI agents" - a way for AI assistants to discover, share, and use reusable capabilities.

What is MCP?

Model Context Protocol (MCP) is an open standard that enables AI applications to securely access external tools and data sources. It provides a consistent way for AI agents to interact with various services.

Key Features

• 🔍 Discovery - Search for skills by keywords, category, or author
• 📥 Retrieval - Get complete skill content including all attachments
• 📤 Publishing - Upload new skills or update existing ones
• 🔒 Security - Automatic scanning with 16 built-in SkillsGuard rules
• 💬 Feedback - Community-driven quality improvement system
• 💾 Caching - Local caching for offline usage
• 📦 Smart Installation - Auto-detects platform (Cursor, Codex, CodeBuddy, etc.) and creates appropriate directories
• 🎯 Multi-Platform - Supports all major AI agent platforms with platform-specific defaults

Installation

# From the project root
npm install

# Build the MCP server
npm run build --workspace=@open-skills-hub/mcp-server

Usage

Running the Server

# Development mode (with auto-reload)
npm run dev --workspace=@open-skills-hub/mcp-server

# Production mode
npm start --workspace=@open-skills-hub/mcp-server

Configuration

The server uses the same configuration as other SkillsHub packages. Configuration is loaded from:

1. Environment variables
2. ~/.open-skills-hub/config.json
3. Default values

Key configuration options:

{
  "dataDir": "~/.open-skills-hub/data",
  "apiUrl": "http://localhost:3001",
  "scanner": {
    "enabled": true,
    "timeout": 5000,
    "maxFileSize": 1048576
  },
  "retry": {
    "maxAttempts": 3,
    "backoffMs": 1000,
    "maxBackoffMs": 30000
  }
}

Integrating with AI Agents

Cursor IDE

Add to your Cursor configuration (~/.cursor/config.json or project .cursor/settings.json):

{
  "mcpServers": {
    "open-skills-hub": {
      "command": "node",
      "args": ["/path/to/SkillsHub/packages/mcp-server/dist/index.js"]
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "open-skills-hub": {
      "command": "node",
      "args": ["/path/to/SkillsHub/packages/mcp-server/dist/index.js"]
    }
  }
}

Available Tools

The MCP server provides 7 core tools for skill management:

Discovery & Retrieval

skills_search

Search for skills by keywords, category, or author.

Parameters:

• query (optional): Search keywords
• category (optional): Filter by category (e.g., "utility", "development")
• author (optional): Filter by author (e.g., "@official", "@user")
• limit (optional): Maximum results (default: 10, max: 100)

Example:

{
  "query": "pdf parser",
  "category": "utility",
  "limit": 5
}

skills_get

Retrieve complete skill content including SKILL.md and all attachments.

Parameters:

• name (required): Full skill name with optional scope (e.g., "@official/pdf-parser")
• version (optional): Specific version (e.g., "1.0.0"). Defaults to latest.

Example:

{
  "name": "@official/pdf-parser",
  "version": "1.2.0"
}

skills_list_cached

List all skills stored in local cache with metadata.

Parameters: None

Publishing & Installation

skills_publish

Publish a skill to the hub.

⚠️ Recommended: Use the CLI tool instead for better stability:

node packages/cli/dist/index.js publish <path> -s <scope> -v <version> -y

Parameters:

• path (required): Absolute path to skill directory containing SKILL.md
• scope (optional): Namespace (e.g., "@user", "@official")
• version (optional): Semantic version (e.g., "1.0.0")

skills_install

Download and install a skill to a directory. Automatically detects your platform (Cursor, Codex, CodeBuddy, etc.) and uses the appropriate default directory, or you can specify a custom path.

Parameters:

• name (required): Full skill name (must match search results exactly)
• targetDir (optional): Absolute path to installation directory. If omitted, uses platform-specific default
• platform (optional): Target platform ("cursor", "codex", "codebuddy", "claude", "anthropic"). Auto-detected if not specified
• version (optional): Specific version to install. Defaults to latest

Platform Default Directories:

• Cursor: ~/.cursor/skills
• Codex: ~/.codex/skills
• CodeBuddy: ~/.codebuddy/skills
• Claude: ~/.claude/skills
• Generic: ~/.skills

Example 1 - Auto-detect platform:

{
  "name": "@official/pdf-parser"
}
// Automatically installs to ~/.cursor/skills/pdf-parser (if Cursor is detected)

Example 2 - Specify platform:

{
  "name": "@official/pdf-parser",
  "platform": "cursor"
}
// Installs to ~/.cursor/skills/pdf-parser

Example 3 - Custom directory:

{
  "name": "@official/pdf-parser",
  "targetDir": "/Users/george/projects/my-app/skills"
}
// Installs to the specified custom directory

Note: Directories are created automatically if they don't exist.

Quality & Safety

skills_scan

Perform security scanning on skill content.

Parameters:

• content (required): Text content to scan (typically SKILL.md or script code)

Returns:

• Security score (0-100)
• Severity level (safe, low, medium, high, critical)
• Detailed issue list

skills_feedback

Submit feedback to help improve skill quality.

Parameters:

• name (required): Full skill name
• type (required): Feedback type ("success", "failure", "suggestion", "bug")
• rating (required): Rating from 1-5 stars
• version (optional): Skill version. Defaults to latest.
• comment (optional): Detailed feedback text

Example:

{
  "name": "@official/pdf-parser",
  "type": "success",
  "rating": 5,
  "comment": "Works perfectly for extracting text from PDFs!"
}

Architecture

Local-First Design

All data is stored locally in SQLite databases:

• ~/.open-skills-hub/data/skills.db - Main skills database
• ~/.open-skills-hub/data/feedback-queue.db - Offline feedback queue
• ~/.open-skills-hub/cache/ - Cached skill content

Security

All published skills are automatically scanned using SkillsGuard with 16 built-in security rules:

• Dangerous command detection (rm -rf, format, etc.)
• Sensitive path access checks
• Code injection prevention
• Environment variable exposure detection
• Network security validation
• And more...

Feedback System

Feedback is queued locally and processed asynchronously:

1. Feedback submitted via skills_feedback
2. Stored in local SQLite queue
3. Automatically retried with exponential backoff
4. Persists across server restarts

Error Handling

The server uses MCP's standard error codes:

• InvalidParams (-32602): Missing or invalid parameters
• InternalError (-32603): Server-side errors
• MethodNotFound (-32601): Unknown tool name

All error messages are clear and actionable to help AI agents correct their requests.

Development

Building

npm run build --workspace=@open-skills-hub/mcp-server

Testing

# Run with verbose logging
DEBUG=open-skills-hub:* npm run dev --workspace=@open-skills-hub/mcp-server

Project Structure

mcp-server/
├── src/
│   ├── index.ts       # Main server implementation
│   └── queue.ts       # Feedback queue processor
├── dist/              # Compiled output
└── package.json

Troubleshooting

Server won't start

1. Check that dependencies are installed: npm install
2. Verify the build completed: npm run build --workspace=@open-skills-hub/mcp-server
3. Check logs for configuration errors

Tool calls fail

1. Verify parameter names match exactly (case-sensitive)
2. Ensure required parameters are provided
3. For skills_install:
   • Only name is required - targetDir is optional and auto-detected
   • Verify the skill name matches search results exactly
   • Check that custom paths (if provided) are absolute, not relative
4. Check error messages - they provide specific guidance on what's wrong

Skills not found

1. Check if the API server is running: npm run dev --workspace=@open-skills-hub/api
2. Verify skills exist in database: sqlite3 ~/.open-skills-hub/data/hub.db "SELECT * FROM skills;"
3. Try publishing a test skill using the CLI

Platform not detected correctly

If auto-detection doesn't work as expected:

1. Manually specify the platform:

   {
     "name": "@official/skill-name",
     "platform": "cursor"
   }

2. Or provide explicit target directory:

   {
     "name": "@official/skill-name",
     "targetDir": "/Users/george/.cursor/skills"
   }

3. Check platform-specific directories exist:

   • Cursor: ~/.cursor/skills
   • Codex: ~/.codex/skills
   • CodeBuddy: ~/.codebuddy/skills

4. If none exist, the system will use ~/.skills as fallback

Learn More

• SkillsHub Documentation
• Model Context Protocol
• MCP SDK Documentation

License

MIT - See LICENSE for details.