npm package: @open-skills-hub/mcp-server
Description: Model Context Protocol (MCP) server for Open Skills Hub - enabling AI agents to discover, publish, and manage reusable skills through a standardized protocol
Author: Open Skills Hub Team
Latest version: 1.0.0

# 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)](https://modelcontextprotocol.io) 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

```bash
# From the project root
npm install

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

## Usage

### Running the Server

```bash
# 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:

```json
{
  "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`):

```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`:

```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:**
```typescript
{
  "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:**
```typescript
{
  "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:
```bash
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:**
```typescript
{
  "name": "@official/pdf-parser"
}
// Automatically installs to ~/.cursor/skills/pdf-parser (if Cursor is detected)
```

**Example 2 - Specify platform:**
```typescript
{
  "name": "@official/pdf-parser",
  "platform": "cursor"
}
// Installs to ~/.cursor/skills/pdf-parser
```

**Example 3 - Custom directory:**
```typescript
{
  "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:**
```typescript
{
  "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

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

### Testing

```bash
# 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:
   ```json
   {
     "name": "@official/skill-name",
     "platform": "cursor"
   }
   ```

2. Or provide explicit target directory:
   ```json
   {
     "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](../../README.md)
- [Model Context Protocol](https://modelcontextprotocol.io)
- [MCP SDK Documentation](https://github.com/modelcontextprotocol/sdk)

## License

MIT - See [LICENSE](../../LICENSE) for details.