easy-skill-server 0.1.0

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 Docker

# Executar com Docker
docker run -p 8000:8000 \
  -v ./skills:/skills:ro \
  -e SKILLS_DIR=/skills \
  easy-skill-server:latest

Ou use docker-compose.yml:

version: '3.8'

services:
  skillserver:
    image: easy-skill-server:latest
    ports:
      - "8000:8000"
    volumes:
      - ./skills:/skills:ro
    environment:
      SKILLS_DIR: /skills
      LOG_LEVEL: INFO

docker-compose up -d

📁 Estrutura de Skills

Segue o padrão serpro-skills (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

server = create_server(
    skills_dir="./skills",      # Diretório das skills
    host="0.0.0.0",              # Host (padrão: 0.0.0.0)
    port=8000,                   # Porta (padrão: 8000)
    name="MySkillServer",        # Nome do servidor
    version="1.0.0",             # Versão
    log_level="INFO",            # DEBUG, INFO, WARNING, ERROR
    run=True                     # Iniciar automaticamente
)

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)

🐳 Docker

Build Local

docker build -t easy-skill-server:latest .

Configuração via Variáveis de Ambiente

Variável	Descrição	Padrão
SKILLS_DIR	Diretório das skills	/skills
SERVER_HOST	Host para bind	0.0.0.0
SERVER_PORT	Porta do servidor	8000
SERVER_NAME	Nome do servidor	SkillServer
SERVER_VERSION	Versão do servidor	0.1.0
LOG_LEVEL	Nível de log	INFO

Healthcheck

A imagem inclui healthcheck automático:

docker ps  # Verifica health status

🏗️ Arquitetura

O projeto segue princípios SOLID:

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

entrypoint.py          # Entrypoint Docker

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 https://git.serpro/vital/easy-skill-server.git
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
make docker-build   # Constrói imagem Docker
make docker-run     # Executa container

📦 Publicação

Para publicar no repositório Nexus do Serpro, 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