easy-skill-server 0.1.0__py3-none-any.whl

easy_skill_server-0.1.0.dist-info/METADATA

@@ -0,0 +1,325 @@
+Metadata-Version: 2.4
+Name: easy-skill-server
+Version: 0.1.0
+Summary: Biblioteca para servir Agent Skills via Model Context Protocol (MCP)
+Author-email: Serpro <vital@serpro.gov.br>
+License: MIT
+Project-URL: Homepage, https://git.serpro/vital/easy-skill-server
+Project-URL: Documentation, https://git.serpro/vital/easy-skill-server/docs
+Project-URL: Repository, https://git.serpro/vital/easy-skill-server
+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"
+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 Docker
+
+```bash
+# 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`:
+
+```yaml
+version: '3.8'
+
+services:
+  skillserver:
+    image: easy-skill-server:latest
+    ports:
+      - "8000:8000"
+    volumes:
+      - ./skills:/skills:ro
+    environment:
+      SKILLS_DIR: /skills
+      LOG_LEVEL: INFO
+```
+
+```bash
+docker-compose up -d
+```
+
+## 📁 Estrutura de Skills
+
+Segue o padrão [serpro-skills](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
+
+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
+
+```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)
+```
+
+## 🐳 Docker
+
+### Build Local
+
+```bash
+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:
+```bash
+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
+
+- **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 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
+
+```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
+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](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

easy_skill_server-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+easy_skill_server-0.1.0.dist-info/licenses/LICENSE,sha256=iVl3kAJMX40N7eqQ1iuCxaJrGpS8LKPySSilg23A88w,1108
+skillserver/__init__.py,sha256=X1joF0r8p-Krz6otMiduLo_9qWUirYmjOhvsTTKi6_I,639
+skillserver/discovery.py,sha256=t1hIDYBy_VXqA4V7oQlfAMS_AsvogK65tz-l9W2IUd4,9640
+skillserver/models.py,sha256=24Aw7k-4U7jjB8kBbkde0sXHpE-c45gl2OfyxiMUwNU,2237
+skillserver/server.py,sha256=BAvnImAZ5TDS-jZLObfFoYrphO18yBYF7A2P5TIOpGU,6430
+skillserver/tools.py,sha256=EZBgXMDIoU_nHnDx5Unz8SrHAJPzMq9h23aLi9TZ5fs,6292
+skillserver/utils.py,sha256=4-dKL3h8cS8n-INFV9F4QTMoyEN9jiEpnyrXkHXnMnc,2772
+easy_skill_server-0.1.0.dist-info/METADATA,sha256=RPoZbNJcSqSuRXRs1ajz-e1uVLChI7XaOO9EbowAK2Y,8264
+easy_skill_server-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+easy_skill_server-0.1.0.dist-info/top_level.txt,sha256=3prbGi8MA7t4uR5xXfqMJJpJvQeTuZS2P7lKCmC5iDk,12
+easy_skill_server-0.1.0.dist-info/RECORD,,

easy_skill_server-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

easy_skill_server-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Serpro - Serviço Federal de Processamento de Dados
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

easy_skill_server-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+skillserver

skillserver/__init__.py

@@ -0,0 +1,30 @@
+"""
+SkillServer MCP - Biblioteca para servir Agent Skills via Model Context Protocol.
+
+Esta biblioteca permite que qualquer pessoa suba um servidor de skills
+facilmente usando MCP (Model Context Protocol) da Anthropic.
+
+Exemplo de uso:
+    ```python
+    from skillserver import create_server
+    
+    # Criar e iniciar servidor
+    create_server(
+        skills_dir="./skills",
+        host="0.0.0.0",
+        port=8000
+    )
+    ```
+"""
+
+from .models import Skill, SkillResource
+from .server import SkillServer, create_server
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Skill",
+    "SkillResource",
+    "SkillServer",
+    "create_server",
+]

skillserver/discovery.py

@@ -0,0 +1,261 @@
+"""
+Descoberta de Skills no sistema de arquivos.
+
+Seguindo o princípio Single Responsibility (SOLID), esta classe tem
+apenas a responsabilidade de descobrir e carregar skills do disco.
+
+A lógica de descoberta está isolada e pode ser facilmente testada
+ou substituída por outra implementação (Open/Closed Principle).
+
+Suporta dois formatos:
+1. Padrão serpro-skills: Diretórios com SKILL.md + references/ + scripts/ + assets/
+2. Formato simples: Arquivos .md soltos (fallback)
+"""
+
+import logging
+from pathlib import Path
+from typing import Iterator
+
+from .models import Skill, SkillResource
+from .utils import generate_skill_name, get_mime_type, parse_frontmatter
+
+logger = logging.getLogger(__name__)
+
+
+class SkillDiscovery:
+    """
+    Responsável por descobrir e carregar Agent Skills de um diretório.
+    
+    Esta classe implementa o padrão Repository, abstraindo a forma
+    como as skills são armazenadas e carregadas.
+    
+    Suporta o padrão serpro-skills (agentskills.io):
+    - skills/nome-da-skill/SKILL.md (obrigatório)
+    - skills/nome-da-skill/references/ (opcional)
+    - skills/nome-da-skill/scripts/ (opcional)
+    - skills/nome-da-skill/assets/ (opcional)
+    """
+    
+    # Diretórios de recursos padrão do serpro-skills
+    RESOURCE_DIRS = ["references", "scripts", "assets"]
+    
+    def __init__(self, skills_dir: Path):
+        """
+        Inicializa o discovery com um diretório de skills.
+        
+        Args:
+            skills_dir: Diretório raiz contendo as skills
+            
+        Raises:
+            ValueError: Se o diretório não existir
+        """
+        self.skills_dir = Path(skills_dir)
+        if not self.skills_dir.exists():
+            raise ValueError(f"Skills directory not found: {self.skills_dir}")
+        if not self.skills_dir.is_dir():
+            raise ValueError(f"Path is not a directory: {self.skills_dir}")
+    
+    def discover_skills(self) -> list[Skill]:
+        """
+        Descobre todas as skills no diretório configurado.
+        
+        Procura primeiro por diretórios com SKILL.md (padrão serpro-skills).
+        Se não encontrar nenhum, procura por arquivos .md soltos (fallback).
+        
+        Returns:
+            Lista de objetos Skill descobertos
+            
+        Note:
+            Prioriza o padrão de diretórios sobre arquivos soltos para
+            compatibilidade com agentskills.io e serpro-skills.
+        """
+        skills = []
+        
+        # Primeiro tenta o padrão serpro-skills: diretórios com SKILL.md
+        skill_dirs = self._find_skill_directories()
+        
+        if skill_dirs:
+            logger.info(f"Using serpro-skills pattern (SKILL.md in directories)")
+            for skill_dir in skill_dirs:
+                try:
+                    skill_file = skill_dir / "SKILL.md"
+                    skill = self._load_skill(skill_file)
+                    skills.append(skill)
+                    logger.info(f"Discovered skill: {skill.name} (from {skill_dir.name}/)")
+                except Exception as e:
+                    logger.error(f"Failed to load skill from {skill_dir}: {e}")
+                    continue
+        else:
+            # Fallback: busca arquivos .md soltos
+            logger.info(f"No SKILL.md found, trying simple .md files pattern")
+            for skill_file in self.skills_dir.rglob("*.md"):
+                # Ignora arquivos SKILL.md órfãos 
+                if skill_file.name == "SKILL.md":
+                    continue
+                    
+                try:
+                    skill = self._load_skill(skill_file)
+                    skills.append(skill)
+                    logger.info(f"Discovered skill: {skill.name}")
+                except Exception as e:
+                    logger.error(f"Failed to load skill {skill_file}: {e}")
+                    continue
+        
+        if not skills:
+            logger.warning(f"No skills found in {self.skills_dir}")
+        
+        return skills
+    
+    def _find_skill_directories(self) -> list[Path]:
+        """
+        Encontra diretórios que contêm SKILL.md.
+        
+        Returns:
+            Lista de diretórios que contêm um arquivo SKILL.md
+        """
+        skill_dirs = []
+        
+        # Busca recursivamente por arquivos SKILL.md
+        for skill_file in self.skills_dir.rglob("SKILL.md"):
+            skill_dir = skill_file.parent
+            # Evita diretórios escondidos ou especiais
+            if not any(part.startswith('.') or part.startswith('_') 
+                      for part in skill_dir.relative_to(self.skills_dir).parts):
+                skill_dirs.append(skill_dir)
+        
+        return skill_dirs
+    
+    def discover_resources(self, skill: Skill) -> list[SkillResource]:
+        """
+        Descobre recursos estáticos associados a uma skill.
+        
+        Segue o padrão serpro-skills/agentskills.io:
+        - references/: Documentação de referência, APIs, esquemas
+        - scripts/: Scripts executáveis (Python, Bash, etc)
+        - assets/: Templates, ícones, arquivos base
+        
+        Args:
+            skill: Skill para buscar recursos
+            
+        Returns:
+            Lista de recursos descobertos
+        """
+        resources = []
+        skill_dir = skill.file_path.parent
+        
+        # Busca nos diretórios padrão do serpro-skills
+        for resource_dir_name in self.RESOURCE_DIRS:
+            resource_dir = skill_dir / resource_dir_name
+            
+            if resource_dir.exists() and resource_dir.is_dir():
+                # Busca recursivamente todos os arquivos
+                for file_path in resource_dir.rglob("*"):
+                    if file_path.is_file():
+                        try:
+                            resource = self._create_resource(
+                                skill, 
+                                file_path, 
+                                resource_type=resource_dir_name
+                            )
+                            resources.append(resource)
+                            logger.debug(
+                                f"Discovered {resource_dir_name} resource: "
+                                f"{file_path.name} for skill {skill.name}"
+                            )
+                        except Exception as e:
+                            logger.error(f"Failed to load resource {file_path}: {e}")
+        
+        # Também busca arquivos soltos no diretório da skill (exceto SKILL.md)
+        for file_path in skill_dir.iterdir():
+            if (file_path.is_file() and 
+                file_path.name != "SKILL.md" and 
+                file_path.suffix != ".md"):
+                try:
+                    resource = self._create_resource(skill, file_path)
+                    resources.append(resource)
+                except Exception as e:
+                    logger.error(f"Failed to load resource {file_path}: {e}")
+        
+        if resources:
+            logger.info(f"Discovered {len(resources)} resources for skill {skill.name}")
+        
+        return resources
+    
+    def _load_skill(self, file_path: Path) -> Skill:
+        """
+        Carrega uma skill de um arquivo markdown.
+        
+        Args:
+            file_path: Caminho do arquivo .md
+            
+        Returns:
+            Objeto Skill carregado
+            
+        Raises:
+            ValueError: Se o arquivo não puder ser parseado
+        """
+        # Lê o conteúdo do arquivo
+        content = file_path.read_text(encoding="utf-8")
+        
+        # Parse frontmatter e conteúdo
+        metadata, instructions = parse_frontmatter(content)
+        
+        # Extrai informações da skill
+        skill_name = metadata.get("name") or generate_skill_name(file_path)
+        title = metadata.get("title") or skill_name.replace("-", " ").title()
+        description = metadata.get("description") or title
+        
+        # Cria objeto Skill
+        return Skill(
+            name=skill_name,
+            title=title,
+            description=description,
+            instructions=instructions.strip(),
+            file_path=file_path,
+            metadata=metadata,
+        )
+    
+    def _create_resource(
+        self, 
+        skill: Skill, 
+        file_path: Path,
+        resource_type: str | None = None
+    ) -> SkillResource:
+        """
+        Cria um objeto SkillResource para um arquivo.
+        
+        Args:
+            skill: Skill dona do recurso
+            file_path: Caminho do arquivo do recurso
+            resource_type: Tipo do recurso (references, scripts, assets) ou None
+            
+        Returns:
+            Objeto SkillResource criado
+        """
+        skill_dir = skill.file_path.parent
+        
+        # Gera URI única para o recurso
+        relative_path = file_path.relative_to(skill_dir)
+        uri = f"skill://{skill.name}/{relative_path}"
+        
+        # Determina tipo MIME
+        mime_type = get_mime_type(file_path)
+        
+        # Gera descrição baseada no tipo de recurso
+        if resource_type == "references":
+            description = f"Reference documentation: {file_path.name}"
+        elif resource_type == "scripts":
+            description = f"Script: {file_path.name}"
+        elif resource_type == "assets":
+            description = f"Asset file: {file_path.name}"
+        else:
+            description = f"Resource for {skill.title}: {file_path.name}"
+        
+        return SkillResource(
+            uri=uri,
+            name=file_path.name,
+            skill_name=skill.name,
+            file_path=file_path,
+            mime_type=mime_type,
+            description=description,
+        )

skillserver/models.py

@@ -0,0 +1,71 @@
+"""
+Modelos de dados para Skills e Resources.
+
+Seguindo o princípio Single Responsibility (SOLID), este módulo contém
+apenas as definições de dados, sem lógica de negócio.
+"""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class Skill:
+    """
+    Representa uma Agent Skill descoberta no sistema.
+    
+    Attributes:
+        name: Nome único da skill (ex: "hello-world")
+        title: Título legível da skill
+        description: Descrição breve da skill
+        instructions: Instruções completas em markdown
+        file_path: Caminho do arquivo da skill
+        metadata: Metadados adicionais do frontmatter YAML
+    """
+    name: str
+    title: str
+    description: str
+    instructions: str
+    file_path: Path
+    metadata: dict[str, Any] = field(default_factory=dict)
+    
+    def __post_init__(self):
+        """Valida e normaliza os dados após inicialização."""
+        if not self.name:
+            raise ValueError("Skill name cannot be empty")
+        if not self.title:
+            self.title = self.name.replace("-", " ").title()
+        if not self.description:
+            self.description = self.title
+
+
+@dataclass
+class SkillResource:
+    """
+    Representa um recurso estático associado a uma skill.
+    
+    Resources podem ser imagens, arquivos de dados, ou qualquer outro
+    arquivo que a skill precise disponibilizar para o agente.
+    
+    Attributes:
+        uri: URI única do recurso (ex: "skill://hello-world/image.png")
+        name: Nome do arquivo
+        skill_name: Nome da skill dona do recurso
+        file_path: Caminho físico do arquivo
+        mime_type: Tipo MIME do recurso
+        description: Descrição opcional do recurso
+    """
+    uri: str
+    name: str
+    skill_name: str
+    file_path: Path
+    mime_type: str = "application/octet-stream"
+    description: str = ""
+    
+    def __post_init__(self):
+        """Valida os dados após inicialização."""
+        if not self.uri.startswith("skill://"):
+            raise ValueError(f"Resource URI must start with 'skill://': {self.uri}")
+        if not self.file_path.exists():
+            raise FileNotFoundError(f"Resource file not found: {self.file_path}")

skillserver/server.py

@@ -0,0 +1,211 @@
+"""
+Servidor MCP principal para Agent Skills.
+
+Este módulo implementa o servidor MCP que orquestra todos os componentes
+seguindo os princípios SOLID:
+
+- Single Responsibility: SkillServer apenas orquestra componentes
+- Open/Closed: Extensível via herança, fechado para modificação
+- Liskov Substitution: Pode ser substituído por subclasses
+- Interface Segregation: Interfaces pequenas e focadas
+- Dependency Inversion: Depende de abstrações (SkillDiscovery, SkillTools)
+"""
+
+import logging
+from pathlib import Path
+
+import uvicorn
+from fastmcp import FastMCP
+
+from .discovery import SkillDiscovery
+from .models import Skill, SkillResource
+from .tools import SkillTools
+
+logger = logging.getLogger(__name__)
+
+
+class SkillServer:
+    """
+    Servidor MCP para servir Agent Skills via HTTP/SSE.
+    
+    Esta classe implementa o padrão Facade, fornecendo uma interface
+    simples para um subsistema complexo (MCP + Skills + Resources).
+    
+    Attributes:
+        skills_dir: Diretório contendo as skills
+        name: Nome do servidor MCP
+        version: Versão do servidor
+        mcp: Instância do FastMCP
+    """
+    
+    def __init__(
+        self,
+        skills_dir: str | Path,
+        name: str = "SkillServer",
+        version: str = "0.1.0",
+        log_level: str = "INFO",
+    ):
+        """
+        Inicializa o servidor MCP.
+        
+        Args:
+            skills_dir: Diretório contendo as skills
+            name: Nome do servidor MCP
+            version: Versão do servidor
+            log_level: Nível de logging (DEBUG, INFO, WARNING, ERROR)
+            
+        Raises:
+            ValueError: Se o diretório de skills não existir
+        """
+        self.skills_dir = Path(skills_dir)
+        self.name = name
+        self.version = version
+        
+        # Setup de logging
+        self._setup_logging(log_level)
+        
+        # Inicializa FastMCP
+        self.mcp = FastMCP(name=name, version=version)
+        
+        # Inicializa componentes (Dependency Injection)
+        self.discovery = SkillDiscovery(self.skills_dir)
+        self.tools = SkillTools(self.mcp)
+        
+        # Descobre e registra skills
+        self._discover_and_register()
+        
+        logger.info(f"{name} v{version} initialized")
+    
+    def _setup_logging(self, log_level: str) -> None:
+        """
+        Configura o sistema de logging.
+        
+        Args:
+            log_level: Nível de logging desejado
+        """
+        numeric_level = getattr(logging, log_level.upper(), None)
+        if not isinstance(numeric_level, int):
+            numeric_level = logging.INFO
+        
+        logging.basicConfig(
+            level=numeric_level,
+            format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+        )
+    
+    def _discover_and_register(self) -> None:
+        """
+        Descobre skills e recursos, registrando-os no MCP.
+        
+        Este método orquestra o processo de descoberta e registro,
+        delegando responsabilidades para os componentes especializados.
+        """
+        # Descobre skills
+        skills = self.discovery.discover_skills()
+        
+        if not skills:
+            logger.warning("No skills found - server will start but have no tools")
+            return
+        
+        # Registra skills como ferramentas MCP
+        self.tools.register_skills(skills)
+        
+        # Descobre e registra recursos
+        all_resources = []
+        for skill in skills:
+            resources = self.discovery.discover_resources(skill)
+            all_resources.extend(resources)
+        
+        if all_resources:
+            self.tools.register_resources(all_resources)
+        
+        logger.info(
+            f"Discovery complete: {len(skills)} skills, "
+            f"{len(all_resources)} resources"
+        )
+    
+    def get_asgi_app(self):
+        """
+        Retorna a aplicação ASGI do FastMCP.
+        
+        Returns:
+            Aplicação ASGI pronta para uso com uvicorn ou outro servidor
+            
+        Note:
+            Este método permite usar o servidor com outros ASGI servers
+            ou integrá-lo em aplicações existentes.
+        """
+        return self.mcp.http_app()
+    
+    def run(self, host: str = "0.0.0.0", port: int = 8000) -> None:
+        """
+        Inicia o servidor MCP.
+        
+        Args:
+            host: Endereço para bind (padrão: 0.0.0.0)
+            port: Porta para o servidor (padrão: 8000)
+            
+        Note:
+            Este método bloqueia a execução até o servidor ser encerrado.
+        """
+        logger.info(f"Starting MCP server on {host}:{port}")
+        logger.info(f"Skills directory: {self.skills_dir.absolute()}")
+        logger.info(f"Serving {len(self.tools.skills)} skills")
+        
+        # Usa uvicorn para servir a aplicação ASGI
+        uvicorn.run(
+            self.get_asgi_app(),
+            host=host,
+            port=port,
+            log_level="info",
+        )
+
+
+def create_server(
+    skills_dir: str | Path,
+    host: str = "0.0.0.0",
+    port: int = 8000,
+    name: str = "SkillServer",
+    version: str = "0.1.0",
+    log_level: str = "INFO",
+    run: bool = True,
+) -> SkillServer:
+    """
+    Função de conveniência para criar e opcionalmente iniciar um servidor MCP.
+    
+    Esta é a API pública principal da biblioteca, fornecendo uma forma
+    simples e direta de criar servidores de skills.
+    
+    Args:
+        skills_dir: Diretório contendo as skills
+        host: Endereço para bind (padrão: 0.0.0.0)
+        port: Porta para o servidor (padrão: 8000)
+        name: Nome do servidor MCP
+        version: Versão do servidor
+        log_level: Nível de logging (DEBUG, INFO, WARNING, ERROR)
+        run: Se True, inicia o servidor imediatamente
+        
+    Returns:
+        Instância do SkillServer criado
+        
+    Example:
+        >>> # Criar e iniciar servidor
+        >>> create_server("./skills")
+        
+        >>> # Criar servidor sem iniciar (para testes ou uso customizado)
+        >>> server = create_server("./skills", run=False)
+        >>> app = server.get_asgi_app()
+        
+    Raises:
+        ValueError: Se o diretório de skills não existir
+    """
+    server = SkillServer(
+        skills_dir=skills_dir,
+        name=name,
+        version=version,
+        log_level=log_level,
+    )
+    
+    if run:
+        server.run(host=host, port=port)
+    
+    return server

skillserver/tools.py

@@ -0,0 +1,187 @@
+"""
+Ferramentas MCP para interação com Agent Skills.
+
+Seguindo o princípio Single Responsibility, esta classe é responsável
+apenas por registrar as ferramentas (tools) do MCP que permitem
+aos agentes interagirem com as skills.
+
+Dependency Inversion: Esta classe depende de abstrações (Skill, SkillResource)
+ao invés de implementações concretas.
+"""
+
+import logging
+from pathlib import Path
+from typing import Any
+
+from fastmcp import FastMCP
+
+from .models import Skill, SkillResource
+
+logger = logging.getLogger(__name__)
+
+
+class SkillTools:
+    """
+    Registra e gerencia as ferramentas MCP para acesso às skills.
+    
+    Esta classe segue o padrão Strategy, encapsulando a lógica de
+    registro de ferramentas e permitindo que seja facilmente testada
+    ou substituída.
+    """
+    
+    def __init__(self, mcp: FastMCP):
+        """
+        Inicializa o gerenciador de ferramentas.
+        
+        Args:
+            mcp: Instância do FastMCP onde registrar as ferramentas
+        """
+        self.mcp = mcp
+        self.skills: dict[str, Skill] = {}
+        self.resources: dict[str, SkillResource] = {}
+    
+    def register_skills(self, skills: list[Skill]) -> None:
+        """
+        Registra uma lista de skills e suas ferramentas.
+        
+        Args:
+            skills: Lista de skills a serem registradas
+        """
+        for skill in skills:
+            self.skills[skill.name] = skill
+        
+        self._register_tools()
+        logger.info(f"Registered {len(skills)} skills with MCP tools")
+    
+    def register_resources(self, resources: list[SkillResource]) -> None:
+        """
+        Registra recursos estáticos das skills.
+        
+        Args:
+            resources: Lista de recursos a serem registrados
+        """
+        for resource in resources:
+            self.resources[resource.uri] = resource
+            # Registra cada recurso como um MCP resource
+            self._register_resource(resource)
+        
+        logger.info(f"Registered {len(resources)} skill resources")
+    
+    def _register_tools(self) -> None:
+        """Registra as ferramentas MCP principais."""
+        
+        @self.mcp.tool()
+        def list_skills() -> list[dict[str, str]]:
+            """
+            Lista todas as Agent Skills disponíveis.
+            
+            Returns:
+                Lista de skills com name, title e description
+            """
+            return [
+                {
+                    "name": skill.name,
+                    "title": skill.title,
+                    "description": skill.description,
+                }
+                for skill in self.skills.values()
+            ]
+        
+        @self.mcp.tool()
+        def get_skill_instructions(skill_name: str) -> str:
+            """
+            Obtém as instruções completas de uma skill específica.
+            
+            Args:
+                skill_name: Nome da skill (ex: "hello-world")
+                
+            Returns:
+                Instruções em markdown da skill
+                
+            Raises:
+                ValueError: Se a skill não existir
+            """
+            skill = self.skills.get(skill_name)
+            if not skill:
+                available = ", ".join(self.skills.keys())
+                raise ValueError(
+                    f"Skill '{skill_name}' not found. "
+                    f"Available skills: {available}"
+                )
+            
+            return skill.instructions
+        
+        @self.mcp.tool()
+        def search_skills(query: str) -> list[dict[str, str]]:
+            """
+            Busca skills por palavra-chave no título ou descrição.
+            
+            Args:
+                query: Texto para buscar
+                
+            Returns:
+                Lista de skills que correspondem à busca
+            """
+            query_lower = query.lower()
+            results = []
+            
+            for skill in self.skills.values():
+                if (query_lower in skill.title.lower() or
+                    query_lower in skill.description.lower() or
+                    query_lower in skill.name.lower()):
+                    results.append({
+                        "name": skill.name,
+                        "title": skill.title,
+                        "description": skill.description,
+                    })
+            
+            return results
+        
+        @self.mcp.tool()
+        def get_skill_metadata(skill_name: str) -> dict[str, Any]:
+            """
+            Obtém metadados completos de uma skill.
+            
+            Args:
+                skill_name: Nome da skill
+                
+            Returns:
+                Dicionário com todos os metadados da skill
+            """
+            skill = self.skills.get(skill_name)
+            if not skill:
+                raise ValueError(f"Skill '{skill_name}' not found")
+            
+            return {
+                "name": skill.name,
+                "title": skill.title,
+                "description": skill.description,
+                "file_path": str(skill.file_path),
+                "metadata": skill.metadata,
+            }
+    
+    def _register_resource(self, resource: SkillResource) -> None:
+        """
+        Registra um recurso individual como MCP resource.
+        
+        Args:
+            resource: Recurso a ser registrado
+        """
+        # Para recursos de texto, podemos disponibilizar o conteúdo diretamente
+        if resource.mime_type.startswith("text/"):
+            @self.mcp.resource(resource.uri)
+            def get_text_resource() -> str:
+                """Retorna conteúdo de recurso de texto."""
+                return resource.file_path.read_text(encoding="utf-8")
+        else:
+            # Para recursos binários, disponibilizamos metadados
+            @self.mcp.resource(resource.uri)
+            def get_binary_resource() -> dict[str, str]:
+                """Retorna metadados de recurso binário."""
+                return {
+                    "uri": resource.uri,
+                    "name": resource.name,
+                    "mime_type": resource.mime_type,
+                    "description": resource.description,
+                    "note": "Binary resource - download via file system or API",
+                }

skillserver/utils.py

@@ -0,0 +1,108 @@
+"""
+Funções utilitárias para parsing e manipulação de arquivos.
+
+Seguindo o princípio Single Responsibility, cada função tem uma
+responsabilidade específica e bem definida.
+"""
+
+import mimetypes
+import re
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+def parse_frontmatter(content: str) -> tuple[dict[str, Any], str]:
+    """
+    Extrai frontmatter YAML e conteúdo markdown de um arquivo.
+    
+    Args:
+        content: Conteúdo completo do arquivo markdown
+        
+    Returns:
+        Tupla com (metadados, conteúdo_markdown)
+        
+    Example:
+        >>> content = '''---
+        ... title: My Skill
+        ... ---
+        ... # Content here'''
+        >>> metadata, body = parse_frontmatter(content)
+        >>> metadata['title']
+        'My Skill'
+    """
+    # Regex para capturar frontmatter YAML
+    pattern = r'^---\s*\n(.*?)\n---\s*\n(.*)$'
+    match = re.match(pattern, content, re.DOTALL)
+    
+    if not match:
+        return {}, content
+    
+    yaml_content = match.group(1)
+    markdown_content = match.group(2)
+    
+    try:
+        metadata = yaml.safe_load(yaml_content) or {}
+    except yaml.YAMLError as e:
+        raise ValueError(f"Invalid YAML frontmatter: {e}")
+    
+    return metadata, markdown_content
+
+
+def get_mime_type(file_path: Path) -> str:
+    """
+    Determina o tipo MIME de um arquivo baseado na extensão.
+    
+    Args:
+        file_path: Caminho do arquivo
+        
+    Returns:
+        String com o tipo MIME (ex: "image/png", "text/plain")
+        
+    Example:
+        >>> get_mime_type(Path("image.png"))
+        'image/png'
+    """
+    mime_type, _ = mimetypes.guess_type(str(file_path))
+    return mime_type or "application/octet-stream"
+
+
+def is_text_file(file_path: Path) -> bool:
+    """
+    Verifica se um arquivo é de texto ou binário.
+    
+    Args:
+        file_path: Caminho do arquivo
+        
+    Returns:
+        True se for arquivo de texto, False caso contrário
+    """
+    mime_type = get_mime_type(file_path)
+    return mime_type.startswith("text/") or mime_type in [
+        "application/json",
+        "application/xml",
+        "application/javascript",
+    ]
+
+
+def generate_skill_name(file_path: Path) -> str:
+    """
+    Gera um nome único para a skill baseado no caminho do arquivo.
+    
+    Args:
+        file_path: Caminho do arquivo da skill
+        
+    Returns:
+        Nome da skill (ex: "hello-world", "category/advanced-skill")
+        
+    Example:
+        >>> generate_skill_name(Path("skills/hello-world.md"))
+        'hello-world'
+    """
+    # Remove extensão e normaliza o nome
+    name = file_path.stem
+    # Converte para kebab-case
+    name = re.sub(r'[^a-z0-9]+', '-', name.lower())
+    name = name.strip('-')
+    return name or "unnamed-skill"