# Skills Registry MCP Server

Intelligent discovery and management of Claude Skills using MCP (Model Context Protocol).

## Features

- 🔍 **Semantic Search** - Find skills using natural language
- ⭐ **Ratings & Reviews** - Community-curated skill quality
- 💾 **Favorites** - Save your most-used skills
- 📈 **Trending** - Discover popular skills
- 📤 **Upload** - Add custom skills
- 🏷️ **Categories & Tags** - Organized skill library

## Quick Start (Docker)

### Prerequisites

- Docker and Docker Compose
- OpenAI API key (for semantic search) or Anthropic API key

### 1. Clone and Configure

```bash
# Copy environment template
cp .env.example .env

# Edit .env and add your API key (use your preferred editor)
# On Mac/Linux: vi .env  or  code .env
# On Windows: notepad .env

# Or just echo it directly:
echo "OPENAI_API_KEY=sk-your-key-here" >> .env
```

### 2. Start Services

```bash
# Start PostgreSQL, Redis, and MCP server
docker-compose up -d

# View logs
docker-compose logs -f mcp-server
```

### 3. Verify and Import Skills

```bash
# Check services are running
docker-compose ps

# Import skills from GitHub (60+ skills from multiple repos)
./scripts/import_github_skills.sh

# Verify import
docker-compose exec postgres psql -U skills -d skills_registry -c "SELECT COUNT(*) FROM skills;"
```

This will import skills from:
- **Anthropic Official Skills** (docx, pdf, pptx, xlsx, theme-factory, etc.)
- **Obra's Superpowers** (test-driven-development, git workflows, etc.)
- **Composio Community Skills** (changelog-generator, content-research-writer, etc.)
- **Other Community Skills** (epub, ffuf, tapestry, etc.)

## Usage with NCP

### Install NCP

```bash
npm install -g @portel/ncp
```

### Add Skills Registry MCP

```bash
# Add to NCP configuration
ncp add skills-registry npx @your-org/skills-registry-mcp

# Or connect to local Docker instance
ncp add skills-registry http://localhost:8000
```

### Test MCP Tools

```bash
# Search for skills
ncp find "pdf extraction"

# List categories
ncp run skills-registry:skill_list_categories

# Get trending skills
ncp run skills-registry:skill_trending --params '{"timeframe":"week"}'
```

## MCP Tools Available

### `skill_search`
Search for skills using natural language or filters.

```json
{
  "query": "create presentations with charts",
  "category": "documents",
  "min_rating": 4.0,
  "limit": 10
}
```

### `skill_get`
Fetch complete skill content and metadata.

```json
{
  "skill_id": "pdf-master-v2",
  "user_id": "user-123"
}
```

### `skill_favorite_add`
Add skill to favorites.

```json
{
  "skill_id": "docx-advanced",
  "user_id": "user-123"
}
```

### `skill_rate`
Rate a skill 1-5 stars.

```json
{
  "skill_id": "xlsx-wizard",
  "user_id": "user-123",
  "rating": 5,
  "review": "Excellent for data analysis!"
}
```

### `skill_trending`
Get popular skills.

```json
{
  "limit": 10,
  "timeframe": "week"
}
```

### `skill_upload`
Add a custom skill.

```json
{
  "name": "API Documentation Generator",
  "description": "Generate OpenAPI specs from code",
  "skill_md_content": "# Skill Content Here...",
  "category": "development",
  "tags": ["api", "documentation"],
  "author_id": "user-123",
  "visibility": "private"
}
```

## Development

### Project Structure

```
skills-registry-mcp/
├── docker-compose.yml      # Service orchestration
├── Dockerfile              # MCP server container
├── init.sql                # Database schema
├── requirements.txt        # Python dependencies
├── src/
│   ├── __init__.py
│   ├── server.py          # FastMCP server
│   ├── database.py        # PostgreSQL operations
│   ├── search.py          # Semantic search
│   └── models.py          # Data models
└── skills_storage/        # Local skill files
```

### Local Development

```bash
# Install dependencies
pip install -r requirements.txt

# Set environment variables
export DATABASE_URL=postgresql://skills:skills_dev_password@localhost:5432/skills_registry
export OPENAI_API_KEY=your-key-here

# Run server directly
python -m src.server
```

### Import Existing Skills

```bash
# Import skills from /mnt/skills/
python scripts/import_skills.py --source /mnt/skills/ --category core
```

## Database Schema

See `init.sql` for complete schema. Key tables:

- `skills` - Skill metadata and content
- `skill_ratings` - User ratings and reviews
- `skill_favorites` - User favorites
- `skill_usage` - Analytics tracking
- `skill_stats` - Computed statistics view

## Configuration

### Environment Variables

- `DATABASE_URL` - PostgreSQL connection string
- `REDIS_URL` - Redis connection string
- `SKILLS_STORAGE_PATH` - Local filesystem path for SKILL.md files
- `OPENAI_API_KEY` - For semantic search (optional)
- `ANTHROPIC_API_KEY` - Alternative for semantic search (optional)

### Docker Compose Services

- `postgres` - PostgreSQL 15 with pgvector
- `redis` - Redis 7 for caching
- `mcp-server` - FastMCP server

## Roadmap

- [ ] Phase 1: MVP with local search ✅
- [ ] Phase 2: Semantic search with embeddings ✅
- [ ] Phase 3: Import existing skills from `/mnt/skills/`
- [ ] Phase 4: Cloud-hosted registry option
- [ ] Phase 5: Web UI for browsing
- [ ] Phase 6: Skill versioning system

## License

MIT