npm package: @luckybalabalaya/skillsmp-mcp-server
Description: MCP server for SkillSMP - Search, discover, and manage AI coding skills with intelligent tiering
Author: Anilcan Cakir
Latest version: 1.6.4

<div align="center">

# 🎯 SkillSMP MCP Server

**Intelligent Skill Management for AI Agents**

*Search • Discover • Vet • Tier • Auto-Load*

[![npm version](https://img.shields.io/npm/v/@luckybalabalaya/skillsmp-mcp-server?style=for-the-badge&logo=npm&color=CB3837)](https://www.npmjs.com/package/@luckybalabalaya/skillsmp-mcp-server)
[![CI](https://img.shields.io/github/actions/workflow/status/Luckybalabalaya/skillsmp-mcp-server/ci.yml?style=for-the-badge&logo=github&label=CI)](https://github.com/Luckybalabalaya/skillsmp-mcp-server/actions/workflows/ci.yml)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-3178C6?style=for-the-badge&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![License](https://img.shields.io/badge/License-MIT-green?style=for-the-badge)](LICENSE)

</div>

---

## ✨ What is SkillSMP MCP Server?

An MCP (Model Context Protocol) server that connects AI agents to the [SkillSMP](https://skillsmp.com) marketplace. It provides **intelligent skill discovery**, **security vetting**, and **automatic tiering** to help agents find and use the right skills at the right time.

<table>
<tr>
<td width="50%">

### 🔍 Smart Discovery
- AI-powered semantic search
- Context-aware recommendations
- Auto-load high-confidence skills

</td>
<td width="50%">

### 🛡️ Security First
- Pattern-based vulnerability scanning
- Risk level assessment
- Pre-install vetting

</td>
</tr>
<tr>
<td width="50%">

### 📊 Intelligent Tiering
- Multi-dimensional scoring
- Feedback-driven promotion
- Automatic demotion

</td>
<td width="50%">

### 🚀 Easy Integration
- 18 MCP tools
- Works with Claude, Cursor, Codex
- Zero-config setup

</td>
</tr>
</table>

---

## 📦 Installation

```bash
# Install globally
npm install -g @luckybalabalaya/skillsmp-mcp-server

# Or use with npx
npx @luckybalabalaya/skillsmp-mcp-server
```

### Quick Setup

Add to your MCP client configuration:

```json
{
  "mcpServers": {
    "skillsmp": {
      "command": "npx",
      "args": ["@luckybalabalaya/skillsmp-mcp-server"],
      "env": {
        "SKILLSMP_API_KEY": "your-api-key"
      }
    }
  }
}
```

---

## 🛠️ MCP Tools

### Core Tools

| Tool | Description |
|:-----|:------------|
| `skillsmp_search` | 🔍 Search skills by keywords, category, tags |
| `skillsmp_ai_search` | 🤖 AI-powered semantic search with relevance scores |
| `skillsmp_preview` | 👀 Preview skill metadata and content |
| `skillsmp_install` | 📥 Install skill to specified namespace |
| `skillsmp_list` | 📋 List installed skills with filters |
| `skillsmp_load` | ⬆️ Load skill content into context |
| `skillsmp_unload` | ⬇️ Unload skill from active context |

### Security & Vetting

| Tool | Description |
|:-----|:------------|
| `skillsmp_vet` | 🔒 Security scan skill content for risks |

### Tier Management

| Tool | Description |
|:-----|:------------|
| `skillsmp_promote` | ⬆️ Promote skill to higher tier |
| `skillsmp_demote` | ⬇️ Demote skill to lower tier |
| `skillsmp_rate` | ⭐ Rate a skill (helpful/not-helpful/harmful) |
| `skillsmp_stats` | 📊 View usage statistics |
| `skillsmp_metrics` | 📈 Get detailed metrics for a skill |
| `skillsmp_evaluate` | 🎯 Get tier evaluation with scoring breakdown |

### Discovery

| Tool | Description |
|:-----|:------------|
| `skillsmp_discover` | 🔎 AI-powered skill discovery based on context |
| `skillsmp_auto_discover` | 🚀 Automatically discover and recommend skills |
| `skillsmp_add_context` | 📝 Add message to discovery context |

---

## 🏆 Intelligent Tiering System

Skills progress through tiers based on **multi-dimensional scoring**, not just usage frequency:

```
┌─────────────────────────────────────────────────────────────┐
│                      TIER PROGRESSION                        │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│   ┌──────────┐    ┌──────────┐    ┌──────────┐             │
│   │  SANDBOX │ ──▶│   WARM   │ ──▶│    HOT   │             │
│   │   🔸      │    │   🔶     │    │   🔥     │             │
│   └──────────┘    └──────────┘    └──────────┘             │
│       New           Regular          Frequent               │
│       Skills         Usage            Success               │
│                                                              │
└─────────────────────────────────────────────────────────────┘
```

### Scoring Dimensions

| Metric | Weight | Description |
|:-------|:------:|:------------|
| 🎯 **Relevance** | 35% | How well skill matches current context |
| ✅ **Success Rate** | 25% | Ratio of helpful vs not-helpful feedback |
| ⏰ **Recency** | 20% | Recent usage weighted higher |
| 🗂️ **Project Match** | 15% | Match with project languages/frameworks |
| 📝 **Content Quality** | 5% | Skill metadata completeness |

---

## 🔐 Security Vetting

All skills are scanned before installation:

| Risk Level | Description |
|:-----------|:------------|
| 🟢 **LOW** | Safe to install |
| 🟡 **MEDIUM** | Review recommended |
| 🟠 **HIGH** | Manual review required |
| 🔴 **CRITICAL** | Installation blocked |

**Scanned for:**
- 🔑 Secret/API key patterns
- ⚠️ Suspicious code patterns (`eval`, `exec`, etc.)
- 💀 Dangerous system commands
- 📦 Insecure dependencies

---

## 🎯 Skill Orchestrator (v1.4.0)

The new **Skill Orchestrator** provides intelligent skill automation:

```
User Message → Intent Detection → Skill Matching → Auto Load → Feedback Loop
```

### Components

| Component | Description |
|:----------|:------------|
| **IntentEngine** | Analyzes user messages to detect intent (code generation, debugging, testing, etc.) |
| **TriggerConfigManager** | Manages skill trigger rules (builtin, learned, user-defined) |
| **SkillMatcher** | Matches intents to relevant skills using rules and AI search |
| **SkillRunner** | Executes skill installation, loading, and unloading |
| **FeedbackLoop** | Collects feedback, evaluates effectiveness, auto-adjusts rules |

### Usage

```typescript
import { SkillOrchestrator } from '@luckybalabalaya/skillsmp-mcp-server';

const orchestrator = new SkillOrchestrator(client, storage, metrics);

// Analyze user message and get skill recommendations
const result = await orchestrator.processMessage("Help me debug this TypeScript error");

// result.intent.type === 'debugging'
// result.matches === [{ skillId: 'debugging', confidence: 'high', ... }]
// result.loaded === [successful loads]
```

### Learning from Feedback

The orchestrator learns from user feedback:

```typescript
// Positive feedback - promotes skill and learns rule
await orchestrator.submitPositiveFeedback('debugging', 'Fixed the issue quickly');

// Negative feedback - demotes skill and adjusts rules
await orchestrator.submitNegativeFeedback('debugging', 'Not relevant for this context');

// Switch feedback - learns alternative skill
await orchestrator.submitSwitchFeedback('debugging', 'tdd-workflow', 'Actually need to write tests');
```

---

## 🤖 Auto-Discovery

The auto-discovery system analyzes conversation context and proactively recommends relevant skills:

```javascript
// Add conversation context
skillsmp_add_context({
  role: "user",
  content: "I need to implement react hooks for state management"
})

// Trigger discovery
skillsmp_auto_discover({ force: true })

// Result:
// ✅ Detected: TypeScript, React
// 📚 Recommended: react-hooks-patterns (score: 0.92)
// 🚀 Auto-loaded: react-hooks-patterns
```

### Auto-Load Thresholds

| Confidence | Threshold | Behavior |
|:-----------|:----------|:---------|
| `high` | 0.4 | Aggressive auto-loading |
| `medium` | 0.6 | Balanced (default) |
| `low` | 0.8 | Conservative |

---

## ⚙️ Configuration

```bash
# Required
SKILLSMP_API_KEY=sk_live_xxx           # Your SkillSMP API key
SKILLSMP_BASE_URL=https://skillsmp.com # API base URL

# Optional
SKILLSMP_CACHE_TTL=24                  # Cache TTL in hours
SKILLSMP_AUTO_VET=true                 # Auto-scan on install
SKILLSMP_DEFAULT_NAMESPACE=sandbox     # Default namespace
SKILLSMP_DISCOVERY_MODE=passive        # passive | active
SKILLSMP_DATA_DIR=~/skillsmp           # Data directory
SKILLSMP_AUTO_LOAD_THRESHOLD=medium    # low | medium | high
```

---

## 📁 Project Structure

```
skillsmp-mcp-server/
├── 📂 src/
│   ├── 📄 index.ts              # Entry point
│   ├── 📄 server.ts             # MCP server (18 tools)
│   ├── 📄 config.ts             # Configuration
│   ├── 📂 client/
│   │   └── 📄 skillsmp.ts       # SkillSMP API client
│   ├── 📂 storage/
│   │   └── 📄 manager.ts        # Storage & tier management
│   ├── 📂 metrics/
│   │   ├── 📄 tracker.ts        # Metrics tracking
│   │   └── 📄 types.ts          # Metrics types
│   ├── 📂 discovery/
│   │   ├── 📄 orchestrator.ts   # Discovery orchestration
│   │   ├── 📄 context-analyzer.ts
│   │   └── 📄 skill-recommender.ts
│   ├── 📂 vetting/
│   │   ├── 📄 scanner.ts        # Security scanner
│   │   └── 📄 risk-calculator.ts
│   └── 📂 types/
│       └── 📄 *.ts              # Type definitions
├── 📂 __tests__/
│   ├── 📄 storage.test.ts       # 12 tests
│   └── 📄 metrics.test.ts       # 12 tests
└── 📄 package.json
```

---

## 🧪 Development

```bash
# Install dependencies
npm install

# Development mode
npm run dev

# Build
npm run build

# Test
npm test

# Lint
npm run lint
```

---

## 📄 License

[MIT](LICENSE) © 2024

---

<div align="center">

**Made with ❤️ for AI Agents**

[🌐 SkillSMP](https://skillsmp.com) • [📦 npm](https://www.npmjs.com/package/@luckybalabalaya/skillsmp-mcp-server) • [🐛 Issues](https://github.com/Luckybalabalaya/skillsmp-mcp-server/issues)

</div>