easy-skill-server 0.2.2

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

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 facilmente através do Model Context Protocol 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

pip install easy-skill-server

Uso via 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

# 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:

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:

docker compose up -d

📁 Estrutura de Skills

Segue o padrão 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:

---
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()

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:

# Ativar auto-reload via parâmetro
# ⚠️ Importante: sempre usar if __name__ == '__main__': com reload=True
if __name__ == '__main__':
    create_server(skills_dir="./skills", reload=True)

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

⚠️ Atenção: Ao usar reload=True em Python 3.12+, é obrigatório proteger o código com if __name__ == '__main__': para evitar erros de multiprocessing. Veja AUTO-RELOAD.md para mais detalhes.

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:

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

SkillServer Class

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

• Single Responsibility: Cada classe tem uma responsabilidade
• Open/Closed: Extensível via herança
• Liskov Substitution: Interfaces claras
• Interface Segregation: APIs focadas
• Dependency Inversion: Injeção de dependências

📚 Exemplos

Veja exemplos completos em examples/:

• hello-world.md - Skill básica
• documentation-helper.md - Skill avançada

🧪 Desenvolvimento

# 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

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.

Quick Start para Publicação:

# 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.

📖 Documentação Adicional

• Model Context Protocol (MCP)
• Agent Skills Standard
• FastMCP Framework

📄 Licença

MIT License - veja 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