Metadata-Version: 2.4
Name: claude-skills-mcp-backend
Version: 1.0.2
Summary: Heavy backend for Claude Skills MCP server with vector search (Streamable HTTP)
Project-URL: Homepage, https://github.com/K-Dense-AI/claude-skills-mcp
Project-URL: Documentation, https://github.com/K-Dense-AI/claude-skills-mcp/blob/main/packages/backend/README.md
Project-URL: Repository, https://github.com/K-Dense-AI/claude-skills-mcp
Project-URL: Bug Tracker, https://github.com/K-Dense-AI/claude-skills-mcp/issues
Author-email: K-Dense AI <orion.li@k-dense.ai>
Maintainer-email: K-Dense AI <orion.li@k-dense.ai>
License: Apache-2.0
Keywords: agent,ai,backend,claude,mcp,scientific,skills,vector-search
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <3.13,>=3.12
Requires-Dist: httpx>=0.24.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: sentence-transformers>=2.2.0
Requires-Dist: starlette>=0.27.0
Requires-Dist: torch<3.0.0,>=2.0.0; platform_system == 'Linux'
Requires-Dist: torch>=2.0.0; platform_system != 'Linux'
Requires-Dist: uvicorn>=0.23.0
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'test'
Requires-Dist: pytest-cov>=4.1.0; extra == 'test'
Requires-Dist: pytest>=7.4.0; extra == 'test'
Description-Content-Type: text/markdown

# Claude Skills MCP Backend

Heavy backend server for Claude Skills MCP system with vector search capabilities.

## Overview

This is the backend component of the Claude Skills MCP system. It provides:
- Vector-based semantic search using sentence-transformers
- Skill indexing and retrieval
- MCP protocol via Streamable HTTP transport
- Background skill loading from GitHub and local sources

**Note**: This package is typically auto-installed by the frontend (`claude-skills-mcp`). You only need to install it manually for:
- Remote deployment (hosting your own backend)
- Development and testing
- Standalone usage without the frontend proxy

## Installation

```bash
# Via uv (recommended)
uv tool install claude-skills-mcp-backend

# Via uvx (one-time use)
uvx claude-skills-mcp-backend

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

## Usage

### Run Standalone Server

```bash
# Default (localhost:8765)
claude-skills-mcp-backend

# Custom port
claude-skills-mcp-backend --port 8080

# For remote access
claude-skills-mcp-backend --host 0.0.0.0 --port 8080

# With custom configuration
claude-skills-mcp-backend --config my-config.json

# Verbose logging
claude-skills-mcp-backend --verbose
```

### Configuration

```bash
# Print example configuration
claude-skills-mcp-backend --example-config > config.json

# Edit config.json to customize skill sources, embedding model, etc.

# Run with custom config
claude-skills-mcp-backend --config config.json
```

## Endpoints

When running, the backend exposes:

- **Streamable HTTP MCP**: `http://localhost:8765/mcp`
- **Health Check**: `http://localhost:8765/health`

## Docker Deployment

### Build Image

```bash
docker build -t claude-skills-mcp-backend .
```

### Run Container

```bash
# For local access
docker run -p 8765:8765 claude-skills-mcp-backend

# For remote access
docker run -p 8080:8765 \
  -e HOST=0.0.0.0 \
  claude-skills-mcp-backend --host 0.0.0.0 --port 8765
```

## Dependencies

This package includes heavy dependencies (~250 MB):
- PyTorch (CPU-only on Linux): ~150-200 MB
- sentence-transformers: ~50 MB
- numpy, httpx, fastapi, uvicorn: ~30 MB

**First download may take 60-180 seconds** depending on your internet connection.

## Performance

- **Startup time**: 2-5 seconds (with cached dependencies)
- **First search**: +2-5 seconds (embedding model download, one-time)
- **Query time**: <1 second after models loaded
- **Memory usage**: ~500 MB

## Development

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

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

# Run tests
uv run pytest tests/
```

## Related Packages

- **claude-skills-mcp** (Frontend): Lightweight proxy that auto-installs this backend
- **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)

