easy-skill-server 0.1.0__tar.gz

easy_skill_server-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,292 @@
+# 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/pyproject.toml

@@ -0,0 +1,69 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "easy-skill-server"
+version = "0.1.0"
+description = "Biblioteca para servir Agent Skills via Model Context Protocol (MCP)"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+    { name = "Serpro", email = "vital@serpro.gov.br" }
+]
+keywords = ["mcp", "agent", "skills", "ai", "anthropic"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+
+dependencies = [
+    "fastmcp>=0.4.0",
+    "uvicorn>=0.30.0",
+    "pyyaml>=6.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=4.1.0",
+    "black>=24.0.0",
+    "ruff>=0.3.0",
+    "mypy>=1.8.0",
+    "build>=1.0.0",
+    "twine>=5.0.0",
+]
+
+[project.urls]
+Homepage = "https://git.serpro/vital/easy-skill-server"
+Documentation = "https://git.serpro/vital/easy-skill-server/docs"
+Repository = "https://git.serpro/vital/easy-skill-server"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+
+[tool.black]
+line-length = 88
+target-version = ['py310']
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true

easy_skill_server-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+