@ds9-solutions/mcp 0.1.0 → 0.2.0

package/content/skills/hex-pattern-dart/references/checklist.md

@@ -0,0 +1,34 @@
+# Checklist de review — hexagonal DS9 (Dart)
+
+## Estrutura
+- [ ] Organização por contexto com `domain/{models,ports,services}` e `adapter/{controllers,dtos,repository}`.
+- [ ] Imports relativos dentro de `lib/`.
+- [ ] Nenhum contexto importa `domain`/`adapter` de outro.
+
+## Dependência
+- [ ] `domain` sem import de `adapter`, framework, driver ou tipos de protocolo.
+- [ ] Ports como `abstract interface class` em `domain/ports`.
+- [ ] Repositórios implementam ports e vivem em `adapter/repository`.
+
+## Erros
+- [ ] `TaskEither` + `TaskEither.tryCatch` em toda operação falível.
+- [ ] `BusinessException` → `ClientException` → `MiddlewareException`.
+- [ ] 5xx com mensagem genérica; sem `toString()`/stack no cliente.
+- [ ] Sem `catch (_)` genérico nem exceção lançada entre camadas.
+
+## Composição
+- [ ] Dependências por construtor e montadas no composition root.
+- [ ] Nada instanciado dentro de rota/handler/controller.
+- [ ] `fpdart` presente no `pubspec.yaml` (ou usuário informado).
+
+## Responsabilidades
+- [ ] Controller sem regra de negócio; repositório sem regra de negócio.
+- [ ] Autorização de recurso no service.
+- [ ] DTO fora do `domain`; mapper entre persistência e model.
+
+## Testes
+- [ ] Service testado com fakes das ports (sucesso e cada erro).
+- [ ] `test/` espelha `lib/`.
+
+## Dart
+- [ ] Regras da skill `dart`: nomenclatura, `///` em APIs públicas, OOP, null safety.

package/content/skills/hex-pattern-dart/references/dependency-injection.md

@@ -0,0 +1,32 @@
+# Injeção de dependência e composition root
+
+## Princípio
+
+Existe **um** lugar onde o grafo de dependências é montado (composition root). O restante do código recebe dependências por construtor e só conhece abstrações (ports).
+
+## Regras
+
+1. Dependências entram por construtor, como `final` e por interface.
+2. Nunca instancie service, repositório ou controller dentro de rota/handler/controller.
+3. O composition root escolhe a implementação concreta de cada port.
+4. Ordem de montagem: infraestrutura → repositórios → services → controllers.
+5. Reaproveite instâncias (cache/singleton no composition root) quando o recurso for caro (conexão, cliente HTTP).
+6. Em frameworks com middleware ou provider, use o mecanismo do framework como composition root (ver a skill do framework, ex.: `dart-frog`).
+7. Em testes, o composition root é substituído por fakes das ports.
+
+## Pseudocódigo
+
+```text
+compose():
+  dataSource  = ConcreteDataSource(config)
+  repository  = OrderRepository(dataSource)
+  service     = OrderService(repository)
+  controller  = OrderController(service)
+  return controller
+```
+
+## Evite
+
+- Localizador global (`ServiceLocator.get()`) dentro do `domain`.
+- Dependência criada com `new`/construtor direto dentro do método que a usa.
+- Ler configuração/ambiente fora do composition root.

package/content/skills/hex-pattern-dart/references/error-layers.md

@@ -0,0 +1,27 @@
+# Camadas de erro
+
+Os nomes das camadas são fixos em todo projeto DS9.
+
+| Camada | Tipo | Onde nasce | Campos | Quem consome |
+|---|---|---|---|---|
+| Negócio | `BusinessException` | service / repository | `domainName`, `statusCode`, `message` (segura), `error`, `stackTrace` | controller |
+| Cliente | `ClientException` | controller | `statusCode`, `message` | borda (handler/middleware) |
+| Borda | `MiddlewareException` | middleware / handler | `statusCode`, `message`, `stackTrace?` | resposta final |
+
+## Regras
+
+1. Falhas esperadas viajam como valor: `TaskEither.left(BusinessException(...))`.
+2. `tryCatch` converte qualquer exceção inesperada em `BusinessException`, preservando `error` e `stackTrace` para log.
+3. Mensagem para o cliente é sempre segura. Para 5xx use texto genérico; detalhes ficam no log.
+4. Nunca devolva `error.toString()` nem stack ao cliente.
+5. Evite `catch (_)` genérico sem converter para a camada correta.
+6. `domainName` identifica o contexto de origem e ajuda a rastrear logs.
+
+## Fluxo
+
+```text
+repository.tryCatch(falha) ──► BusinessException
+service repassa / enriquece ──► BusinessException
+controller.mapLeft ──────────► ClientException (5xx genérico)
+borda.match ─────────────────► resposta de protocolo
+```

package/content/skills/hex-pattern-dart/references/layers-and-dependency-rule.md

@@ -0,0 +1,29 @@
+# Camadas e regra de dependência
+
+## Sentido das dependências
+
+```text
+adapter/controllers ─┐
+adapter/dtos ────────┼──► domain/services ──► domain/ports ◄── adapter/repository
+                     │          │
+                     └──────────┴──► domain/models
+```
+
+- `domain` conhece apenas `domain` e `common`.
+- `adapter` conhece `domain` e `common`.
+- O `domain` declara a port; o `adapter/repository` a implementa (inversão de dependência).
+
+## O que pertence a cada camada
+
+- **models:** entidades, value objects, regras que valem em qualquer protocolo ou banco.
+- **ports:** contratos de saída (persistência, mensageria, serviços externos). Nomeie `<Papel>Port`: `OrderRepositoryPort`, `PaymentGatewayPort`.
+- **services:** um caso de uso por método público. Aplicam regra e autorização de recurso.
+- **controllers/dtos:** tudo que depende de protocolo (HTTP, fila, CLI).
+- **repository:** tudo que depende de infraestrutura (banco, API externa).
+
+## Sinais de violação
+
+- `import` de pacote de framework, driver ou `adapter` dentro de `domain/`.
+- DTO ou tipo de request/response aparecendo em assinatura de service.
+- Service que monta SQL, chama HTTP ou lê variável de ambiente.
+- Controller com `if` de regra de negócio.

package/content/skills/hex-pattern-dart/references/persistence.md

@@ -0,0 +1,23 @@
+# Persistência agnóstica
+
+O padrão não prescreve banco nem ORM. Para a tecnologia do projeto, consulte a skill correspondente via `list_skills`/`recommend_for_task` e preserve o que já existe.
+
+## Contrato
+
+- O `domain` declara a port (`OrderRepositoryPort`).
+- O `adapter/repository` implementa a port usando a tecnologia do projeto.
+- Opcionalmente, o repositório delega a um `DataSource` (abstração do acesso físico), facilitando trocar ou simular o banco.
+
+## Mapper
+
+- Modelo de persistência (linha/documento) e model do domínio são tipos distintos.
+- Um mapper converte nos dois sentidos e vive no `adapter/repository`.
+- O `domain` nunca importa o tipo de persistência.
+
+## Regras
+
+1. Toda chamada de I/O dentro de `TaskEither.tryCatch`.
+2. Falha vira `BusinessException` com mensagem segura.
+3. "Não encontrado" é resultado explícito (`left` com status adequado ou `Option`), nunca `null` implícito.
+4. Transação: abra no adapter; o service expõe a operação de negócio completa, sem conhecer a transação.
+5. Migrations seguem a skill de persistência do projeto e não alteram estrutura existente sem pedido.

package/content/skills/hex-pattern-dart/references/ports-and-adapters.md

@@ -0,0 +1,33 @@
+# Ports e adapters
+
+## Ports (saída)
+
+- Declare como `abstract interface class` dentro de `domain/ports/`.
+- Expresse a necessidade do domínio, não a tecnologia: `save(order)`, não `insertRow(map)`.
+- Assinaturas usam apenas models e tipos de `common/`.
+- Toda operação que pode falhar retorna `TaskEither<BusinessException, T>`.
+
+```text
+abstract interface class OrderRepositoryPort
+  TaskEither<BusinessException, Order>  findById(String id)
+  TaskEither<BusinessException, Unit>   save(Order order)
+```
+
+## Adapters de entrada (controllers)
+
+- Recebem o contexto do protocolo (request) a cada chamada de método.
+- Validam o DTO, chamam o service e mapeiam o resultado para resposta.
+- Mapeiam `BusinessException` → `ClientException`; 5xx com mensagem genérica.
+- Recebem o service por construtor; nunca o criam.
+
+## Adapters de saída (repository)
+
+- Implementam a port e escondem o detalhe de persistência.
+- Mapeiam modelo de persistência ↔ model do domínio (mapper dedicado).
+- Envolvem cada chamada externa em `TaskEither.tryCatch` e convertem a falha em `BusinessException`.
+
+## Nomenclatura
+
+- Arquivos `snake_case`; classes `UpperCamelCase`.
+- Port: `<Papel>Port` (`OrderRepositoryPort`). Implementação: nome do papel sem sufixo (`OrderRepository`), sem prefixo `I` e sem sufixo `Impl`.
+- DTO: `<Acao><Entidade>Dto` / `<Entidade>Response`.

package/content/skills/hex-pattern-dart/references/testing.md

@@ -0,0 +1,30 @@
+# Testes na arquitetura hexagonal
+
+## Estratégia
+
+| Alvo | Como testar | Dublês |
+|---|---|---|
+| `model` | Unitário puro | Nenhum |
+| `service` | Unitário com ports falsas | Fakes/mocks das ports |
+| `controller` | Unitário com service falso e contexto de protocolo simulado | Service falso |
+| `repository` | Integração com a tecnologia real ou em memória | Opcional |
+| Borda (rota/handler) | Teste de contrato: status, corpo e método não suportado | Composition root de teste |
+
+## Regras
+
+1. A árvore de `test/` espelha `lib/`.
+2. Teste o caminho feliz **e** cada `left` (erro de negócio, erro inesperado, 5xx genérico).
+3. Verifique que o 5xx não vaza mensagem interna.
+4. Para `TaskEither`, execute com `.run()` e inspecione o `Either` resultante.
+5. Prefira fakes simples a mocks com muitas expectativas quando a port for pequena.
+6. Nenhum teste de `domain` pode precisar de rede, banco ou framework.
+7. Nome: `<comportamento> quando <condição>`.
+
+## Pseudocódigo
+
+```text
+test "retorna Right quando o pedido existe":
+  repo = FakeOrderRepository(with: order)
+  result = await OrderService(repo).getById("1").run()
+  expect(result.isRight)
+```

package/content/skills/mysql/SKILL.md

@@ -5,7 +5,7 @@ description: Diretrizes de modelagem, indexação, migrations, performance e seg
 
 # MySQL — Diretrizes DS9
 
-Convenções obrigatórias para schema, queries e migrations em MySQL (compatível com MariaDB), usadas em conjunto com a skill `typeorm` para a camada de persistência em projetos NestJS/hexagonal.
+Convenções obrigatórias para schema, queries e migrations em MySQL (compatível com MariaDB), usadas com a camada de persistência do projeto.
 
 ## Engine e charset
 
@@ -52,7 +52,7 @@ deleted_at DATETIME(3) NULL          -- se o domínio usa soft delete
 
 ## Migrations
 
-- Toda alteração de schema é uma migration versionada (via TypeORM migrations — ver skill `typeorm`), nunca alteração manual direto no banco de produção.
+- Toda alteração de schema é uma migration versionada (via o mecanismo de migrations do projeto), nunca alteração manual direto no banco de produção.
 - Migrations são **imutáveis** após merge/deploy: para corrigir, crie uma nova migration (nunca edite uma já aplicada em outro ambiente).
 - Toda migration precisa de `up` e `down` reversível. Se o `down` não for possível com segurança (ex.: `DROP COLUMN`), documente explicitamente no corpo da migration.
 - Alterações em tabelas grandes (`ADD COLUMN`, `ADD INDEX`) em produção devem considerar lock de tabela: preferir `ALGORITHM=INPLACE, LOCK=NONE` quando suportado, e avaliar janela de manutenção para tabelas muito grandes.
@@ -66,7 +66,7 @@ deleted_at DATETIME(3) NULL          -- se o domínio usa soft delete
 
 ## Queries
 
-- Nunca concatene valores de usuário diretamente em SQL — sempre use *prepared statements*/query builder parametrizado (via TypeORM). Isso é mandatório contra SQL Injection.
+- Nunca concatene valores de usuário diretamente em SQL — sempre use *prepared statements*/query builder parametrizado (via a biblioteca de acesso a dados do projeto). Isso é mandatório contra SQL Injection.
 - Evite `SELECT *`; liste as colunas necessárias, especialmente em tabelas largas.
 - Pagine toda listagem (`LIMIT`/`OFFSET` ou keyset pagination para datasets grandes); nunca retorne uma tabela inteira sem limite.
 - Prefira keyset pagination (`WHERE id > :lastId ORDER BY id LIMIT :n`) a `OFFSET` alto em tabelas grandes (OFFSET grande é O(n)).

package/content/skills/typescript/SKILL.md

@@ -5,7 +5,7 @@ description: Convenções de TypeScript da DS9 — tipagem estrita, modelagem de
 
 # TypeScript — Diretrizes DS9
 
-Convenções de código TypeScript aplicáveis a qualquer projeto da empresa, incluindo os que usam NestJS (skill `nestjs`) e arquitetura hexagonal (skill `hexagonal`).
+Convenções de código TypeScript aplicáveis a qualquer projeto da empresa, incluindo os que seguem arquitetura hexagonal em geral.
 
 ## Configuração do compilador
 
@@ -31,7 +31,7 @@ function handle(payload: OrderPayload) { return payload.items.map((i) => i.id);
 
 ## Modelagem de domínio
 
-- Use *value objects* para conceitos com regras próprias (ex.: `Email`, `Money`), em vez de `string`/`number` soltos, quando o projeto já segue esse padrão (ver skill `hexagonal`).
+- Use *value objects* para conceitos com regras próprias (ex.: `Email`, `Money`), em vez de `string`/`number` soltos, quando o projeto já segue esse padrão.
 - Invariantes de negócio são validadas no construtor/factory da entidade (`Order.create(...)`), lançando erro de domínio em vez de permitir estado inválido existir.
 - Prefira classes/funções imutáveis (métodos retornam uma nova instância) para entidades de domínio sensíveis a concorrência, salvo quando o projeto adota mutação controlada por padrão.
 
@@ -44,7 +44,7 @@ function handle(payload: OrderPayload) { return payload.items.map((i) => i.id);
 ## Imports e organização de módulos
 
 - Imports absolutos/com alias (`@app/domain/...`) para cruzar camadas, imports relativos (`./`, `../`) dentro do mesmo módulo/camada — configurar via `paths` no `tsconfig.json`.
-- Nunca import circular entre módulos; se ocorrer, é sinal de fronteira de módulo mal definida (revisar com a skill `hexagonal`).
+- Nunca import circular entre módulos; se ocorrer, é sinal de fronteira de módulo mal definida (revisar a organização dos módulos).
 - Um export principal por arquivo quando possível (facilita navegação e testes); evite arquivos "barril" (`index.ts`) gigantes que reexportam dezenas de símbolos sem necessidade.
 
 ## Nulidade e valores opcionais
@@ -57,7 +57,7 @@ function handle(payload: OrderPayload) { return payload.items.map((i) => i.id);
 - Classes/interfaces/tipos: `PascalCase`. Variáveis/funções: `camelCase`. Constantes verdadeiramente globais/imutáveis: `UPPER_SNAKE_CASE`.
 - Nomes de função descrevem a ação (`calculateTotal`, não `total` ou `doIt`); booleanos começam com `is`/`has`/`should` (`isValid`, `hasDiscount`).
 - Evite abreviações não óbvias (`qty` ok se for convenção do domínio; `tmp`, `data2` não).
-- Nome de **arquivo**: `kebab-case`, com sufixo que indica o papel do arquivo quando aplicável (`order-repository.port.ts`, `create-order.use-case.ts`, `typeorm-order.repository.ts`, `order.entity.ts`, `order.controller.ts`, `order.module.ts`). Arquivo de teste usa o mesmo nome base + `.spec.ts`/`.e2e-spec.ts` (ver skill `jest-testing`).
+- Nome de **arquivo**: `kebab-case`, com sufixo que indica o papel do arquivo quando aplicável (`order-repository.port.ts`, `create-order.use-case.ts`, `order.repository.ts`, `order.entity.ts`, `order.controller.ts`, `order.module.ts`). Arquivo de teste usa o mesmo nome base + `.spec.ts`/`.e2e-spec.ts` (seguindo a convenção de testes do projeto).
 
 ## Checklist ao escrever/revisar código TypeScript
 

package/dist/src/content.js

@@ -9,6 +9,7 @@ import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parse as parseYaml } from "yaml";
+import { scanSkillFiles } from "./skill-files.js";
 // Frontmatter = bloco YAML entre dois `---` no topo do arquivo. Aceita \r\n porque os arquivos
 // podem ter sido salvos no Windows.
 const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
@@ -50,9 +51,12 @@ export function resolveContentRoot() {
  * Skill = `skills/<pasta>/SKILL.md` (id = nome da pasta).
  * Agente = `agents/<nome>.agent.md` (id = nome do arquivo; estrutura plana, sem subpastas).
  */
-export function loadEntries(root = resolveContentRoot()) {
+export function loadEntries(root = resolveContentRoot(), 
+// Por padrão os avisos vão para stderr; testes podem injetar um coletor.
+onWarning = (w) => console.error(`[ds9-mcp] aviso: ${w}`)) {
     const entries = [];
     const warnings = [];
+    const fileWarnings = [];
     const skillsDir = join(root, "skills");
     for (const dirent of readdirSync(skillsDir, { withFileTypes: true })) {
         const file = join(skillsDir, dirent.name, "SKILL.md");
@@ -71,7 +75,10 @@ export function loadEntries(root = resolveContentRoot()) {
             name: String(data.name ?? dirent.name),
             description: String(data.description ?? ""),
             body,
+            files: scanSkillFiles(join(skillsDir, dirent.name), fileWarnings),
         });
+        for (const w of fileWarnings.splice(0))
+            warnings.push(`skill "${dirent.name}": ${w}`);
     }
     const agentsDir = join(root, "agents");
     if (existsSync(agentsDir)) {
@@ -87,12 +94,13 @@ export function loadEntries(root = resolveContentRoot()) {
                 name: String(data.name ?? id),
                 description: String(data.description ?? ""),
                 body,
+                files: [],
             });
         }
     }
     // stderr, nunca stdout: no transporte stdio o stdout é o canal do protocolo MCP, e qualquer
     // texto extra nele corromperia a comunicação com a IDE.
     for (const w of warnings)
-        console.error(`[ds9-mcp] aviso: ${w}`);
+        onWarning(w);
     return entries;
 }

package/dist/src/init.js

@@ -78,6 +78,7 @@ Antes de implementar, revisar ou testar código:
 1. Chame a tool \`recommend_for_task\` com a descrição da tarefa.
 2. Leia as skills e agentes recomendados com \`get_skill\` / \`get_agent\` e siga as diretrizes.
 3. Use \`search_guidelines\` para dúvidas pontuais.
+4. Se a skill tiver arquivos complementares, leia-os com \`list_skill_files\` / \`get_skill_file\`.
 ${BLOCK_END}`;
 /**
  * Insere o bloco DS9 num AGENTS.md ou, se já existir, substitui apenas o trecho entre os

package/dist/src/search.js

@@ -68,18 +68,26 @@ export function searchBodies(entries, query, limit = 8) {
         return [];
     const hits = [];
     for (const entry of entries) {
-        entry.body.split(/\r?\n/).forEach((line, i) => {
-            const score = count(line, tokens);
-            if (score > 0 && line.trim()) {
-                hits.push({
-                    kind: entry.kind,
-                    id: entry.id,
-                    line: i + 1,
-                    text: line.trim().slice(0, 300), // limita linhas gigantes
-                    score,
-                });
-            }
-        });
+        // Corpo principal + arquivos complementares (exemplos, referências) da skill.
+        const sources = [
+            { file: undefined, content: entry.body },
+            ...entry.files.map((f) => ({ file: f.path, content: f.text })),
+        ];
+        for (const src of sources) {
+            src.content.split(/\r?\n/).forEach((line, i) => {
+                const score = count(line, tokens);
+                if (score > 0 && line.trim()) {
+                    hits.push({
+                        kind: entry.kind,
+                        id: entry.id,
+                        ...(src.file ? { file: src.file } : {}),
+                        line: i + 1,
+                        text: line.trim().slice(0, 300), // limita linhas gigantes
+                        score,
+                    });
+                }
+            });
+        }
     }
     return hits
         .sort((a, b) => b.score - a.score)

package/dist/src/server.js

@@ -9,12 +9,14 @@
 import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { rankByMetadata, searchBodies } from "./search.js";
+import { isSafeRelativePath, MAX_PATH_LENGTH, SKILL_ID } from "./skill-files.js";
 // Enviado ao host no handshake. Hosts sem suporte nativo a skills/agentes dependem disto (e do
 // bloco no AGENTS.md) para saber que devem consultar o servidor antes de implementar.
 const INSTRUCTIONS = [
     "Servidor de diretrizes oficiais da DS9 (skills por tecnologia e subagentes especializados).",
     "Antes de implementar, revisar ou testar código, chame `recommend_for_task` com a descrição da tarefa",
     "e depois `get_skill` / `get_agent` para ler as diretrizes recomendadas e segui-las.",
+    "Se a skill indicar arquivos complementares, use `list_skill_files` e `get_skill_file` para ler exemplos e referências sob demanda.",
 ].join(" ");
 // Monta a resposta padrão de uma tool. `isError` sinaliza ao LLM que a chamada falhou, mas sem
 // derrubar o protocolo (erro de uso != erro do servidor).
@@ -31,8 +33,21 @@ export function createServer(entries, version = "0.0.0") {
     // Helpers de consulta sobre as entradas.
     const byKind = (kind) => entries.filter((e) => e.kind === kind);
     const find = (kind, id) => entries.find((e) => e.kind === kind && e.id === id);
-    const render = (e) => `# ${e.kind === "skill" ? "Skill" : "Agente"}: ${e.id}\n\n> ${e.description}\n\n${e.body}`;
-    const listing = (items) => items.map((e) => `- ${e.id}: ${e.description}`).join("\n") || "(nenhum resultado)";
+    const render = (e) => `# ${e.kind === "skill" ? "Skill" : "Agente"}: ${e.id}\n\n> ${e.description}\n\n${e.body}` +
+        (e.files.length
+            ? `\n\n---\nArquivos complementares (${e.files.length}): use \`list_skill_files\` e \`get_skill_file\` com skill="${e.id}" para exemplos e referências sob demanda.`
+            : "");
+    const listing = (items) => items
+        .map((e) => `- ${e.id}: ${e.description}${e.files.length ? ` (+${e.files.length} arquivos)` : ""}`)
+        .join("\n") || "(nenhum resultado)";
+    // Erros de skill/arquivo nunca citam caminhos do disco: só ids e caminhos do índice.
+    const skillOrError = (skill) => {
+        const entry = find("skill", skill);
+        return entry
+            ? { entry }
+            : { error: text(`skill "${skill}" não encontrada. Disponíveis:\n${listing(byKind("skill"))}`, true) };
+    };
+    const fileList = (e) => e.files.map((f) => `- ${f.path} (${f.size} bytes)${f.description ? `: ${f.description}` : ""}`).join("\n");
     // Skills e agentes têm exatamente a mesma API (list/get/prompt/resource). Em vez de duplicar o
     // código, registramos os dois em um laço; só mudam os nomes e os rótulos.
     for (const [kind, plural, label] of [
@@ -63,7 +78,7 @@ export function createServer(entries, version = "0.0.0") {
             }
             return text(render(entry));
         });
-        // Um prompt por entrada (ex.: `skill-nestjs`). Fica estático porque o catálogo é conhecido na
+        // Um prompt por entrada (ex.: `skill-hex-pattern-dart`). Fica estático porque o catálogo é conhecido na
         // inicialização do servidor.
         for (const entry of byKind(kind)) {
             server.registerPrompt(`${kind}-${entry.id}`, { description: entry.description }, () => ({
@@ -91,6 +106,45 @@ export function createServer(entries, version = "0.0.0") {
             return { contents: [{ uri: uri.href, mimeType: "text/markdown", text: render(entry) }] };
         });
     }
+    // list_skill_files / get_skill_file — carga sob demanda dos arquivos complementares de uma skill.
+    // Só leem o índice em memória montado no carregamento; o cliente nunca informa caminho de disco.
+    const skillSchema = z
+        .string()
+        .regex(SKILL_ID, "id de skill inválido")
+        .describe("Id da skill (veja list_skills)");
+    server.registerTool("list_skill_files", {
+        description: "Lista os arquivos complementares (exemplos, referências) de uma skill DS9, com tamanho e descrição.",
+        inputSchema: { skill: skillSchema },
+        annotations: { readOnlyHint: true },
+    }, async ({ skill }) => {
+        const { entry, error } = skillOrError(skill);
+        if (!entry)
+            return error;
+        return text(entry.files.length
+            ? `Arquivos da skill "${skill}" (leia com get_skill_file):\n${fileList(entry)}`
+            : `A skill "${skill}" não possui arquivos complementares.`);
+    });
+    server.registerTool("get_skill_file", {
+        description: "Retorna o conteúdo de um arquivo complementar de uma skill DS9. Use o caminho exato de list_skill_files.",
+        inputSchema: {
+            skill: skillSchema,
+            path: z
+                .string()
+                .max(MAX_PATH_LENGTH)
+                .describe("Caminho relativo listado por list_skill_files, ex.: examples/entity.dart"),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ skill, path }) => {
+        const { entry, error } = skillOrError(skill);
+        if (!entry)
+            return error;
+        // Busca exata no índice: caminhos fora dele (inclusive `..`, absolutos etc.) simplesmente não existem.
+        const file = isSafeRelativePath(path) ? entry.files.find((f) => f.path === path) : undefined;
+        if (!file) {
+            return text(`Arquivo não encontrado na skill "${skill}". Arquivos válidos:\n${fileList(entry) || "(nenhum)"}`, true);
+        }
+        return text(`# ${skill}/${file.path}\n\n${file.text}`);
+    });
     // search_guidelines — para dúvidas pontuais ("como nomear migrations?") sem ler arquivos inteiros.
     server.registerTool("search_guidelines", {
         description: "Busca um termo no conteúdo de todas as skills e agentes DS9 e devolve as linhas mais relevantes.",
@@ -99,7 +153,9 @@ export function createServer(entries, version = "0.0.0") {
     }, async ({ query, limit }) => {
         const hits = searchBodies(entries, query, limit ?? 8);
         return text(hits.length
-            ? hits.map((h) => `[${h.kind}:${h.id}:L${h.line}] ${h.text}`).join("\n")
+            ? hits
+                .map((h) => `[${h.kind}:${h.id}${h.file ? `:${h.file}` : ""}:L${h.line}] ${h.text}`)
+                .join("\n")
             : "Nenhum trecho encontrado.");
     });
     // recommend_for_task — é a "ativação automática" possível via MCP: compensa a falta de roteamento

package/dist/src/skill-files.js

@@ -0,0 +1,125 @@
+/**
+ * Arquivos complementares de uma skill (`skills/<id>/examples/`, `references/` etc.).
+ *
+ * Segurança — por que é uma allowlist e não uma sanitização de caminho:
+ *  - tudo é indexado UMA vez, no carregamento, pelo próprio servidor;
+ *  - `get_skill_file` só encontra caminhos que estão nesse índice (comparação exata de string);
+ *  - o texto vem da memória: nenhuma chamada de tool toca o disco nem monta caminho com entrada do
+ *    cliente. Não há como escapar da pasta da skill porque o cliente nunca fornece um caminho de
+ *    arquivo, apenas uma chave de busca.
+ * A varredura ainda aplica limites e ignora symlinks, ocultos e extensões fora da lista.
+ */
+import { lstatSync, readdirSync, readFileSync, realpathSync } from "node:fs";
+import { join, sep } from "node:path";
+export const ALLOWED_EXTENSIONS = new Set([
+    ".md",
+    ".dart",
+    ".yaml",
+    ".yml",
+    ".json",
+    ".txt",
+]);
+export const MAX_FILE_BYTES = 100 * 1024;
+export const MAX_FILES_PER_SKILL = 200;
+export const MAX_DEPTH = 4;
+export const MAX_PATH_LENGTH = 200;
+// SKILL.md é servido por `get_skill`; README.md não é copiado pelo `sync-content`, então ignorá-lo
+// aqui mantém o comportamento igual em desenvolvimento e em produção.
+const IGNORED_NAMES = new Set(["skill.md", "readme.md", "node_modules"]);
+/** Id de skill válido: é o nome da pasta, em kebab-case. */
+export const SKILL_ID = /^[a-z0-9][a-z0-9-]{0,63}$/;
+// eslint-disable-next-line no-control-regex
+const CONTROL_CHARS = /[\u0000-\u001f\u007f]/;
+/**
+ * Valida o formato do caminho informado pelo cliente. É uma barreira extra de entrada; a proteção
+ * real é a busca exata no índice. Rejeita tudo que não seja um caminho relativo simples com `/`.
+ */
+export function isSafeRelativePath(path) {
+    if (path.length === 0 || path.length > MAX_PATH_LENGTH)
+        return false;
+    if (CONTROL_CHARS.test(path))
+        return false;
+    if (path.includes("\\") || path.includes(":") || path.includes("%"))
+        return false;
+    if (path.startsWith("/"))
+        return false;
+    return path.split("/").every((seg) => seg !== "" && seg !== "." && seg !== "..");
+}
+const UTF8 = new TextDecoder("utf-8", { fatal: true });
+/** Primeira linha útil do arquivo: título Markdown ou comentário `///`/`//`. */
+function describe(text) {
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (!line)
+            continue;
+        const cleaned = line.replace(/^(#+|\/\/\/?|\*|>)\s*/, "").trim();
+        if (cleaned && cleaned !== "---")
+            return cleaned.slice(0, 160);
+    }
+    return "";
+}
+/**
+ * Varre a pasta de uma skill e devolve os arquivos complementares permitidos, em ordem estável.
+ * Problemas (arquivo grande, extensão proibida, symlink etc.) viram avisos e o arquivo é ignorado:
+ * um item ruim nunca derruba o carregamento das demais skills.
+ */
+export function scanSkillFiles(skillDir, warnings) {
+    const files = [];
+    const rootReal = realpathSync(skillDir);
+    const walk = (dir, prefix, depth) => {
+        for (const name of readdirSync(dir).sort()) {
+            const rel = prefix ? `${prefix}/${name}` : name;
+            const abs = join(dir, name);
+            if (name.startsWith(".") || IGNORED_NAMES.has(name.toLowerCase()))
+                continue;
+            const stat = lstatSync(abs);
+            if (stat.isSymbolicLink()) {
+                warnings.push(`"${rel}" ignorado: link simbólico`);
+                continue;
+            }
+            if (stat.isDirectory()) {
+                if (depth >= MAX_DEPTH)
+                    warnings.push(`"${rel}" ignorado: profundidade acima de ${MAX_DEPTH}`);
+                else
+                    walk(abs, rel, depth + 1);
+                continue;
+            }
+            if (!stat.isFile())
+                continue;
+            const ext = name.includes(".") ? name.slice(name.lastIndexOf(".")).toLowerCase() : "";
+            if (!ALLOWED_EXTENSIONS.has(ext)) {
+                warnings.push(`"${rel}" ignorado: extensão não permitida`);
+                continue;
+            }
+            if (stat.size > MAX_FILE_BYTES) {
+                warnings.push(`"${rel}" ignorado: maior que ${MAX_FILE_BYTES} bytes`);
+                continue;
+            }
+            if (files.length >= MAX_FILES_PER_SKILL) {
+                warnings.push(`"${rel}" ignorado: limite de ${MAX_FILES_PER_SKILL} arquivos por skill`);
+                continue;
+            }
+            if (!rel.split("/").every((s) => isSafeRelativePath(s))) {
+                warnings.push(`"${rel}" ignorado: nome de arquivo inválido`);
+                continue;
+            }
+            // Confinamento: o arquivo real precisa estar dentro da pasta da skill.
+            const real = realpathSync(abs);
+            if (!real.startsWith(rootReal + sep)) {
+                warnings.push(`"${rel}" ignorado: fora da pasta da skill`);
+                continue;
+            }
+            let text;
+            try {
+                text = UTF8.decode(readFileSync(real));
+            }
+            catch {
+                warnings.push(`"${rel}" ignorado: não é texto UTF-8 válido`);
+                continue;
+            }
+            files.push({ path: rel, size: stat.size, description: describe(text), text });
+        }
+    };
+    walk(skillDir, "", 1);
+    return files;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ds9-solutions/mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Servidor MCP da DS9: expõe skills e subagentes oficiais para qualquer IDE/LLM com suporte a MCP",
   "type": "module",
   "license": "UNLICENSED",
@@ -8,7 +8,7 @@
     "ds9-mcp": "dist/src/index.js"
   },
   "files": [
-    "dist",
+    "dist/src",
     "content"
   ],
   "engines": {