Metadata-Version: 2.4
Name: easy-skill-server
Version: 0.2.0
Summary: Biblioteca para servir Agent Skills via Model Context Protocol (MCP)
License: MIT
Keywords: mcp,agent,skills,ai,anthropic
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastmcp>=0.4.0
Requires-Dist: uvicorn>=0.30.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: black>=24.0.0; extra == "dev"
Requires-Dist: ruff>=0.3.0; extra == "dev"
Requires-Dist: mypy>=1.8.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Requires-Dist: watchfiles>=0.20.0; extra == "dev"
Dynamic: license-file

# SkillServer MCP

**Biblioteca Python para servir Agent Skills via Model Context Protocol (MCP)**

SkillServer MCP é uma biblioteca que permite a qualquer pessoa criar e servir [Agent Skills](https://agentskills.io) facilmente através do [Model Context Protocol](https://modelcontextprotocol.io) da Anthropic.

## 🎯 O que é?

Uma biblioteca Python que:
- ✅ Descobre automaticamente skills de um diretório
- ✅ Expõe skills via MCP (HTTP/SSE)
- ✅ Fornece API simples com `create_server()`
- ✅ Inclui imagem Docker pronta para uso
- ✅ Segue princípios SOLID e boas práticas

## 🚀 Quick Start

### Instalação

```bash
pip install easy-skill-server
```

### Uso via Python

```python
from skillserver import create_server

# Cria e inicia servidor de skills
create_server(skills_dir="./skills")
```

Pronto! Seu servidor MCP está rodando em `http://localhost:8000`

### Uso via CLI

```bash
# Executa com configurações padrão (./skills na porta 8000)
python -m skillserver

# Ou configure via variáveis de ambiente
export SKILLS_DIR=/path/to/skills
export SERVER_PORT=9000
python -m skillserver
```

### Uso via Docker

Para usar com Docker, copie e adapte o `docker-compose.yml` disponível no repositório:

```yaml
version: '3.8'

services:
  skillserver-venv:
    image: python:3.11-slim
    container_name: skillserver-venv
    ports:
      - "8000:8000"
    volumes:
      - .:/app
      - container-venv:/venv
    working_dir: /app
    environment:
      SKILLS_DIR: /app/examples/skills
      SERVER_HOST: 0.0.0.0
      SERVER_PORT: 8000
      VIRTUAL_ENV: /venv
    command: >
      bash -c "
      if [ ! -d /venv/lib ]; then
        python -m venv /venv;
      fi &&
      /venv/bin/pip install -r requirements.txt &&
      /venv/bin/pip install -e . &&
      /venv/bin/python -m skillserver
      "

volumes:
  container-venv:
```

Execute com:

```bash
docker compose up -d
```

## 📁 Estrutura de Skills

Segue o padrão [agentskills.io](https://agentskills.io) (Progressive Disclosure):

```
skills/
└── nome-da-skill/
    ├── SKILL.md          # Obrigatório: Metadados + instruções
    ├── references/       # Opcional: Documentação de referência
    ├── scripts/          # Opcional: Scripts auxiliares
    └── assets/           # Opcional: Templates, arquivos
```

### Exemplo de SKILL.md:

```markdown
---
name: minha-skill
description: Descrição curta de quando usar esta skill
---

# Minha Skill

## Contexto e Objetivo
O que esta skill faz e qual problema resolve.

## Instruções de Uso
1. Passo 1
2. Passo 2

## Referências
- Veja [doc.md](references/doc.md) para detalhes
```

### Compatibilidade

Também suporta arquivos `.md` soltos (fallback) se nenhum diretório com `SKILL.md` for encontrado.

## 🔧 API Completa

### `create_server()`

```python
from skillserver import create_server

# Todos os parâmetros são opcionais e podem vir de variáveis de ambiente
server = create_server(
    skills_dir="./skills",      # Diretório das skills (ou SKILLS_DIR)
    host="0.0.0.0",              # Host (ou SERVER_HOST, padrão: 0.0.0.0)
    port=8000,                   # Porta (ou SERVER_PORT, padrão: 8000)
    name="MySkillServer",        # Nome (ou SERVER_NAME, padrão: SkillServer)
    version="1.0.0",             # Versão (ou SERVER_VERSION, padrão: 0.1.0)
    log_level="INFO",            # Log level (ou LOG_LEVEL, padrão: INFO)
    reload=False,                # Auto-reload (ou SERVER_RELOAD, padrão: False)
    run=True                     # Iniciar automaticamente
)
```

#### Auto-Reload para Desenvolvimento

O servidor pode reiniciar automaticamente quando detectar mudanças no diretório de skills:

```python
# Ativar auto-reload via parâmetro
create_server(skills_dir="./skills", reload=True)
```

```bash
# Ou via variável de ambiente
export SERVER_RELOAD=true
python -m skillserver
```

Isso é útil durante o desenvolvimento de skills, pois qualquer modificação nos arquivos `.md`, scripts ou recursos será detectada e o servidor reiniciará automaticamente.

### Variáveis de Ambiente

O `create_server()` lê automaticamente estas variáveis de ambiente:

- `SKILLS_DIR`: Diretório das skills (padrão: `./skills`)
- `SERVER_HOST`: Host para bind (padrão: `0.0.0.0`)
- `SERVER_PORT`: Porta do servidor (padrão: `8000`)
- `SERVER_NAME`: Nome do servidor (padrão: `SkillServer`)
- `SERVER_VERSION`: Versão do servidor (padrão: `0.1.0`)
- `LOG_LEVEL`: Nível de log - DEBUG, INFO, WARNING, ERROR (padrão: `INFO`)
- `SERVER_RELOAD`: Auto-reload ao detectar mudanças - true/false (padrão: `false`)

Exemplo:

```bash
export SKILLS_DIR=/path/to/skills
export SERVER_PORT=9000
export LOG_LEVEL=DEBUG
python -m skillserver
```

### `SkillServer` Class

```python
from skillserver import SkillServer

# Criar servidor sem iniciar automaticamente
server = SkillServer(
    skills_dir="./skills",
    name="MyServer",
    version="1.0.0",
    log_level="DEBUG"
)

# Obter app ASGI para integração customizada
app = server.get_asgi_app()

# Iniciar servidor manualmente
server.run(host="0.0.0.0", port=8000)

# Iniciar com auto-reload (útil para desenvolvimento)
server.run(host="0.0.0.0", port=8000, reload=True)
```

## 🏗️ Arquitetura

O projeto segue princípios SOLID:

```
src/skillserver/
├── __init__.py        # API pública
├── __main__.py        # Entry point para python -m skillserver
├── server.py          # SkillServer (Facade)
├── discovery.py       # SkillDiscovery (Repository)
├── tools.py           # SkillTools (Strategy)
├── models.py          # Skill, SkillResource (Data)
└── utils.py           # Funções utilitárias
```

### Princípios SOLID Aplicados

- **S**ingle Responsibility: Cada classe tem uma responsabilidade
- **O**pen/Closed: Extensível via herança
- **L**iskov Substitution: Interfaces claras
- **I**nterface Segregation: APIs focadas
- **D**ependency Inversion: Injeção de dependências

## 📚 Exemplos

Veja exemplos completos em [`examples/`](examples/):
- [`hello-world.md`](examples/basic/hello-world.md) - Skill básica
- [`documentation-helper.md`](examples/basic/documentation-helper.md) - Skill avançada

## 🧪 Desenvolvimento

```bash
# Clone o repositório
git clone <repository-url>
cd easy-skill-server

# Crie ambiente virtual
python -m venv venv
source venv/bin/activate  # Linux/Mac
# ou
venv\Scripts\activate  # Windows

# Instale em modo desenvolvimento
pip install -e ".[dev]"
# ou use o Makefile
make dev-install

# Execute testes
pytest
# ou
make test

# Testes com cobertura
make test-cov

# Formatação de código
black src/ tests/
ruff check src/ tests/
# ou
make format

# Type checking
mypy src/
# ou
make lint
```

### Comandos Make disponíveis

```bash
make help           # Mostra todos os comandos disponíveis
make install        # Instala o pacote localmente
make dev-install    # Instala com dependências de dev
make test           # Executa testes
make test-cov       # Testes com cobertura
make lint           # Executa linters
make format         # Formata código
make clean          # Limpa arquivos de build
make build          # Gera pacotes de distribuição
```

## 📦 Publicação

Para publicar no repositório PyPI, consulte o guia completo em [PUBLISH.md](PUBLISH.md).

### Quick Start para Publicação:

```bash
# 1. Configure as credenciais (uma vez)
cp .pypirc.example ~/.pypirc
# Edite ~/.pypirc com suas credenciais

# 2. Atualize a versão (se necessário)
make version-patch  # 0.1.0 -> 0.1.1
# ou
make version-minor  # 0.1.0 -> 0.2.0

# 3. Publique
make release
```

Para mais detalhes, incluindo configuração de CI/CD, troubleshooting e instalação a partir do Nexus, veja [PUBLISH.md](PUBLISH.md).

## 📖 Documentação Adicional

- [Model Context Protocol (MCP)](https://modelcontextprotocol.io)
- [Agent Skills Standard](https://agentskills.io)
- [FastMCP Framework](https://github.com/jlowin/fastmcp)

## 📄 Licença

MIT License - veja [LICENSE](LICENSE) para detalhes.

## 🤝 Contribuindo

Contribuições são bem-vindas! Por favor:

1. Fork o projeto
2. Crie uma branch para sua feature (`git checkout -b feature/amazing`)
3. Commit suas mudanças (`git commit -m 'Add amazing feature'`)
4. Push para a branch (`git push origin feature/amazing`)
5. Abra um Pull Request
