claude-skills-mcp 1.0.6
Lightweight MCP proxy for Claude Skills (auto-downloads backend)
License: Apache-2.0
Requires Python: <3.13,>=3.12
Keywords: agent, ai, claude, mcp, proxy, skills

# Claude Skills MCP Frontend

Lightweight MCP proxy for Claude Skills that auto-downloads the heavy backend on demand.

## Overview

This is the frontend component of the Claude Skills MCP system. It's a lightweight proxy (~15 MB) that:
- Starts instantly (<5 seconds)
- Auto-downloads the backend when first needed
- Acts as MCP server (stdio) for Cursor
- Acts as MCP client (HTTP) for the backend
- Returns tool schemas immediately (no backend wait needed)

## Installation

```bash
# Via uvx (recommended for Cursor)
uvx claude-skills-mcp

# Via uv tool (persistent install)
uv tool install claude-skills-mcp

# Via pip
pip install claude-skills-mcp
```

## Usage with Cursor

Add to your Cursor MCP settings (`~/.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "claude-skills": {
      "command": "uvx",
      "args": ["claude-skills-mcp"]
    }
  }
}
```

Restart Cursor and the skills will be available!

### First Run Behavior

On first run, the frontend will:
1. Start immediately (~5 seconds) ✅ **Cursor timeout satisfied!**
2. Return tool schemas to Cursor (instant)
3. Download backend in background (~250 MB, 60-120 seconds)
4. When you first use a tool, you'll see "Loading backend..."
5. Once backend ready, all tools work normally

**Subsequent runs**: Fast! Backend is already installed.

## Configuration

The frontend forwards all arguments to the backend:

```bash
# Custom configuration
uvx claude-skills-mcp --config my-config.json

# Verbose logging
uvx claude-skills-mcp --verbose

# Custom backend port (advanced)
uvx claude-skills-mcp --port 9000
```

## Remote Backend (Future)

```bash
# Connect to hosted backend instead of local
uvx claude-skills-mcp --remote https://skills.k-dense.ai/mcp
```

**Note**: Remote backend support coming in v1.1.0

## How It Works

```
Cursor → Frontend (stdio, ~15 MB)
           ↓
         list_tools() → Returns hardcoded schemas INSTANTLY ✅
           ↓
         [Backend downloads in background...]
           ↓
         call_tool() → Proxies to Backend (HTTP)
           ↓
         Backend (HTTP, ~250 MB) → Performs actual search
```

This architecture solves the Cursor timeout problem by separating:
- **Fast startup** (frontend, minimal dependencies)
- **Heavy processing** (backend, downloads async)

## Dependencies

Frontend only requires:
- `mcp>=1.0.0` (~5 MB)
- `httpx>=0.24.0` (~5 MB)

**Total**: ~15 MB (downloads in <10 seconds)

The backend (`claude-skills-mcp-backend`) is auto-installed on first use.

## Troubleshooting

### "Backend not ready" message

On first run, you'll see this message for 30-120 seconds while the backend downloads. This is normal and only happens once.

### Backend installation fails

Check:
1. Internet connection
2. Disk space (~500 MB free needed)
3. Python 3.12 installed

### Tools not working

Run with verbose logging:
```bash
uvx claude-skills-mcp --verbose
```

Check logs in stderr for backend status.

## Development

```bash
# Clone the monorepo
git clone https://github.com/K-Dense-AI/claude-skills-mcp.git
cd claude-skills-mcp/packages/frontend

# Install in development mode
uv pip install -e ".[test]"

# Run tests
uv run pytest tests/
```

## Related Packages

- **claude-skills-mcp-backend** (Backend): Heavy server with vector search
- **Main Repository**: https://github.com/K-Dense-AI/claude-skills-mcp

## License

Apache License 2.0

Copyright 2025 K-Dense AI (https://k-dense.ai)