@ds9-solutions/mcp 0.1.0

package/dist/src/init.js

@@ -0,0 +1,123 @@
+/**
+ * Comando `init`: configura o servidor `ds9` na IDE do usuário e adiciona as instruções ao
+ * `AGENTS.md` do projeto.
+ *
+ * Por que existe: cada IDE guarda a configuração de MCP em um arquivo/formato próprio. Automatizar
+ * isso elimina o principal atrito de adoção (editar JSON à mão em cada ferramenta).
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+export const PACKAGE_NAME = "@ds9-solutions/mcp";
+export const SERVER_NAME = "ds9";
+// Para suportar uma IDE nova basta acrescentar uma linha aqui, sem alterar a lógica abaixo.
+export const TARGETS = [
+    { id: "claude-code", label: "Claude Code (.mcp.json)", file: ".mcp.json", key: "mcpServers" },
+    {
+        id: "cursor",
+        label: "Cursor (.cursor/mcp.json)",
+        file: join(".cursor", "mcp.json"),
+        key: "mcpServers",
+    },
+    {
+        id: "vscode",
+        label: "VS Code / GitHub Copilot (.vscode/mcp.json)",
+        file: join(".vscode", "mcp.json"),
+        key: "servers",
+        stdioType: true,
+    },
+    {
+        id: "gemini",
+        label: "Gemini CLI (.gemini/settings.json)",
+        file: join(".gemini", "settings.json"),
+        key: "mcpServers",
+    },
+    {
+        id: "windsurf",
+        label: "Windsurf (~/.codeium/windsurf/mcp_config.json)",
+        file: join(homedir(), ".codeium", "windsurf", "mcp_config.json"),
+        global: true,
+        key: "mcpServers",
+    },
+];
+/**
+ * Monta a entrada do servidor: como a IDE deve iniciá-lo (`npx -y @ds9-solutions/mcp`).
+ * `platform` é parâmetro apenas para permitir testar o comportamento do Windows em qualquer SO.
+ */
+export function serverEntry(target, platform = process.platform) {
+    // No Windows, vários hosts não conseguem executar `npx` diretamente (ele é um script .cmd);
+    // passar por `cmd /c` resolve.
+    const base = platform === "win32"
+        ? { command: "cmd", args: ["/c", "npx", "-y", PACKAGE_NAME] }
+        : { command: "npx", args: ["-y", PACKAGE_NAME] };
+    return target.stdioType ? { type: "stdio", ...base } : base;
+}
+/**
+ * Faz merge da entrada `ds9` no JSON existente, sem tocar nos demais servidores do usuário.
+ * É idempotente: rodar `init` duas vezes produz exatamente o mesmo resultado (sem duplicar).
+ */
+export function mergeServerConfig(existing, target, platform) {
+    const current = (existing[target.key] ?? {});
+    return {
+        ...existing,
+        [target.key]: { ...current, [SERVER_NAME]: serverEntry(target, platform) },
+    };
+}
+// Marcadores HTML (invisíveis no Markdown renderizado) delimitam o bloco gerenciado por nós. É por
+// eles que sabemos o que atualizar numa nova execução sem encostar no resto do AGENTS.md.
+const BLOCK_START = "<!-- ds9-mcp:start -->";
+const BLOCK_END = "<!-- ds9-mcp:end -->";
+// Instrução lida pelo agente. É o que faz hosts sem skills nativas consultarem o MCP: o AGENTS.md
+// é lido automaticamente por quase todos eles.
+export const AGENTS_BLOCK = `${BLOCK_START}
+## Diretrizes DS9 (MCP \`ds9\`)
+
+Este projeto segue os padrões oficiais da DS9, disponíveis via servidor MCP \`ds9\`.
+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.
+${BLOCK_END}`;
+/**
+ * Insere o bloco DS9 num AGENTS.md ou, se já existir, substitui apenas o trecho entre os
+ * marcadores (assim novas versões do texto chegam ao rodar `init` de novo), preservando o resto.
+ */
+export function upsertAgentsBlock(existing) {
+    const start = existing.indexOf(BLOCK_START);
+    const end = existing.indexOf(BLOCK_END);
+    if (start !== -1 && end > start) {
+        return existing.slice(0, start) + AGENTS_BLOCK + existing.slice(end + BLOCK_END.length);
+    }
+    // Primeira vez: acrescenta ao final, separado do conteúdo anterior por uma linha em branco.
+    const sep = existing.length === 0 ? "" : existing.endsWith("\n") ? "\n" : "\n\n";
+    return `${existing}${sep}${AGENTS_BLOCK}\n`;
+}
+/** Executa o `init` completo para uma IDE: grava a configuração do MCP e (opcional) o AGENTS.md. */
+export function runInit(target, projectDir, opts = {}) {
+    const configFile = target.global ? target.file : join(projectDir, target.file);
+    let existing = {};
+    if (existsSync(configFile)) {
+        const raw = readFileSync(configFile, "utf8").trim();
+        if (raw) {
+            try {
+                existing = JSON.parse(raw);
+            }
+            catch {
+                // Arquivos como o do VS Code aceitam comentários (JSONC). Reescrever um arquivo que não
+                // conseguimos ler apagaria a configuração do usuário, então preferimos parar e orientar.
+                throw new Error(`${configFile} não é JSON puro (comentários?). Adicione manualmente a entrada "${SERVER_NAME}".`);
+            }
+        }
+    }
+    mkdirSync(dirname(configFile), { recursive: true });
+    writeFileSync(configFile, JSON.stringify(mergeServerConfig(existing, target), null, 2) + "\n");
+    const result = { configFile };
+    if (opts.agentsMd !== false) {
+        const agentsFile = join(projectDir, "AGENTS.md");
+        const current = existsSync(agentsFile) ? readFileSync(agentsFile, "utf8") : "";
+        writeFileSync(agentsFile, upsertAgentsBlock(current));
+        result.agentsFile = agentsFile;
+    }
+    return result;
+}

package/dist/src/search.js

@@ -0,0 +1,88 @@
+// Palavras sem valor de busca (PT/EN). Sem isso, "para" ou "the" pontuariam em tudo.
+const STOPWORDS = new Set([
+    "de",
+    "da",
+    "do",
+    "a",
+    "o",
+    "e",
+    "para",
+    "com",
+    "em",
+    "um",
+    "uma",
+    "the",
+    "and",
+    "for",
+    "to",
+]);
+/**
+ * Normaliza o texto em tokens comparáveis: minúsculas, sem acentos ("segurança" casa com
+ * "seguranca"), separado por qualquer caractere não alfanumérico, sem stopwords e sem tokens de
+ * 1 letra.
+ */
+export function tokenize(text) {
+    return text
+        .toLowerCase()
+        .normalize("NFD")
+        .replace(/[̀-ͯ]/g, "") // remove os acentos separados pelo NFD
+        .split(/[^a-z0-9]+/)
+        .filter((t) => t.length > 1 && !STOPWORDS.has(t));
+}
+/**
+ * Soma quantas vezes cada token da consulta aparece no texto. Cada token conta no máximo 5 vezes,
+ * para que um texto repetitivo não vença só por insistir numa palavra.
+ */
+function count(haystack, tokens) {
+    if (!tokens.length)
+        return 0;
+    const freq = new Map();
+    for (const t of tokenize(haystack))
+        freq.set(t, (freq.get(t) ?? 0) + 1);
+    return tokens.reduce((acc, t) => acc + Math.min(freq.get(t) ?? 0, 5), 0);
+}
+/**
+ * Ranking por metadados (id, nome e descrição) — usado por `list_*` e `recommend_for_task`.
+ * Id/nome pesam 3 e descrição pesa 2 (a descrição é escrita justamente para dizer "quando usar"),
+ * e entradas sem nenhum acerto são descartadas.
+ */
+export function rankByMetadata(entries, query, kind) {
+    const tokens = tokenize(query);
+    return entries
+        .filter((e) => !kind || e.kind === kind)
+        .map((entry) => ({
+        entry,
+        score: count(`${entry.id} ${entry.name}`, tokens) * 3 + count(entry.description, tokens) * 2,
+    }))
+        .filter((s) => s.score > 0)
+        .sort((a, b) => b.score - a.score);
+}
+/**
+ * Busca no corpo completo, linha a linha — usado por `search_guidelines`.
+ * Devolve linhas (e não arquivos inteiros) para economizar contexto do LLM: ele recebe só o
+ * trecho e pode pedir o arquivo completo com `get_skill`/`get_agent` se precisar.
+ */
+export function searchBodies(entries, query, limit = 8) {
+    const tokens = tokenize(query);
+    if (!tokens.length)
+        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,
+                });
+            }
+        });
+    }
+    return hits
+        .sort((a, b) => b.score - a.score)
+        .slice(0, limit)
+        .map(({ score: _score, ...rest }) => rest); // o score é interno, não vai para o cliente
+}

package/dist/src/server.js

@@ -0,0 +1,125 @@
+/**
+ * Definição do servidor MCP: registra as tools, prompts e resources que a IDE/LLM enxerga.
+ *
+ * Por que três formas de expor o mesmo conteúdo: cada host MCP suporta um subconjunto.
+ *  - tools     -> o LLM chama sozinho (universal; é o caminho principal);
+ *  - prompts   -> o usuário aciona manualmente, vira slash command em alguns hosts;
+ *  - resources -> o usuário anexa o conteúdo ao chat (ex.: via `@`) em alguns hosts.
+ */
+import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { rankByMetadata, searchBodies } from "./search.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.",
+].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).
+const text = (t, isError = false) => ({
+    content: [{ type: "text", text: t }],
+    isError,
+});
+/**
+ * Cria o servidor sobre uma lista de entradas já carregada. Receber as entradas por parâmetro
+ * (em vez de ler do disco aqui) permite testar o servidor com conteúdo controlado.
+ */
+export function createServer(entries, version = "0.0.0") {
+    const server = new McpServer({ name: "ds9", version }, { instructions: INSTRUCTIONS });
+    // 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)";
+    // 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 [
+        ["skill", "skills", "skill"],
+        ["agent", "agents", "agente"],
+    ]) {
+        // list_skills / list_agents — descoberta: o LLM vê o que existe sem gastar contexto com o corpo.
+        server.registerTool(`list_${plural}`, {
+            description: `Lista ${plural === "skills" ? "as skills" : "os agentes"} DS9 disponíveis (id e descrição). Opcionalmente filtra por termo.`,
+            inputSchema: { query: z.string().optional().describe("Termo para filtrar") },
+            annotations: { readOnlyHint: true }, // nunca altera nada; hosts podem executar sem pedir confirmação
+        }, async ({ query }) => {
+            const items = query
+                ? rankByMetadata(byKind(kind), query).map((s) => s.entry)
+                : byKind(kind);
+            return text(listing(items));
+        });
+        // get_skill / get_agent — leitura do conteúdo completo. Em id inexistente, lista os válidos
+        // para o LLM se corrigir na próxima chamada, sem precisar de uma ida extra a `list_*`.
+        server.registerTool(`get_${kind}`, {
+            description: `Retorna o conteúdo completo ${kind === "skill" ? "de uma skill" : "de um agente"} DS9 pelo id.`,
+            inputSchema: { name: z.string().describe(`Id do ${label} (veja list_${plural})`) },
+            annotations: { readOnlyHint: true },
+        }, async ({ name }) => {
+            const entry = find(kind, name);
+            if (!entry) {
+                return text(`${label} "${name}" não encontrado. Disponíveis:\n${listing(byKind(kind))}`, true);
+            }
+            return text(render(entry));
+        });
+        // Um prompt por entrada (ex.: `skill-nestjs`). 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 }, () => ({
+                messages: [{ role: "user", content: { type: "text", text: render(entry) } }],
+            }));
+        }
+        // Resources via template `ds9://skills/{id}`: o host lista as URIs disponíveis (`list`) e lê
+        // uma específica sob demanda.
+        server.registerResource(plural, new ResourceTemplate(`ds9://${plural}/{id}`, {
+            list: async () => ({
+                resources: byKind(kind).map((e) => ({
+                    uri: `ds9://${plural}/${e.id}`,
+                    name: e.id,
+                    description: e.description,
+                    mimeType: "text/markdown",
+                })),
+            }),
+        }), {
+            description: `Conteúdo ${plural === "skills" ? "das skills" : "dos agentes"} DS9`,
+            mimeType: "text/markdown",
+        }, async (uri, { id }) => {
+            const entry = find(kind, String(id));
+            if (!entry)
+                throw new Error(`${label} "${String(id)}" não encontrado`);
+            return { contents: [{ uri: uri.href, mimeType: "text/markdown", text: render(entry) }] };
+        });
+    }
+    // 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.",
+        inputSchema: { query: z.string().min(2), limit: z.number().int().min(1).max(25).optional() },
+        annotations: { readOnlyHint: true },
+    }, 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")
+            : "Nenhum trecho encontrado.");
+    });
+    // recommend_for_task — é a "ativação automática" possível via MCP: compensa a falta de roteamento
+    // por `description` que os hosts nativos de skills têm. O LLM descreve a tarefa e recebe quais
+    // skills/agentes ler. Sem correspondência, devolve o catálogo para ele escolher sozinho.
+    server.registerTool("recommend_for_task", {
+        description: "Dada a descrição de uma tarefa de desenvolvimento, recomenda as skills e agentes DS9 que devem ser lidos e seguidos. Chame ANTES de implementar.",
+        inputSchema: { task: z.string().min(3).describe("Descrição da tarefa") },
+        annotations: { readOnlyHint: true },
+    }, async ({ task }) => {
+        const skills = rankByMetadata(entries, task, "skill")
+            .slice(0, 5)
+            .map((s) => s.entry);
+        const agents = rankByMetadata(entries, task, "agent")
+            .slice(0, 3)
+            .map((s) => s.entry);
+        if (!skills.length && !agents.length) {
+            return text(`Nenhuma correspondência direta. Skills disponíveis:\n${listing(byKind("skill"))}\n\nAgentes:\n${listing(byKind("agent"))}`);
+        }
+        return text(`Skills recomendadas (use get_skill):\n${listing(skills)}\n\nAgentes recomendados (use get_agent):\n${listing(agents)}`);
+    });
+    return server;
+}

package/dist/test/mcp.test.js

@@ -0,0 +1,112 @@
+/**
+ * Testes do pacote, com o runner nativo do Node (`node:test`).
+ *
+ * Por que `node:test`: evita configurar Jest + ts-jest com ESM e não adiciona dependência.
+ * Os testes usam o conteúdo REAL do plugin, então também falham se alguém quebrar o frontmatter
+ * de uma skill ou agente (ex.: remover a `description`).
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { loadEntries, parseFrontmatter } from "../src/content.js";
+import { createServer } from "../src/server.js";
+import { rankByMetadata, searchBodies } from "../src/search.js";
+import { TARGETS, mergeServerConfig, runInit, upsertAgentsBlock } from "../src/init.js";
+const entries = loadEntries();
+/**
+ * Conecta um cliente MCP de verdade ao servidor, em memória (sem processo nem stdio). Assim os
+ * testes exercitam o protocolo completo — o mesmo caminho que uma IDE usaria.
+ */
+async function connect() {
+    const [a, b] = InMemoryTransport.createLinkedPair();
+    const client = new Client({ name: "test", version: "0" });
+    await Promise.all([createServer(entries).connect(a), client.connect(b)]);
+    return client;
+}
+// Extrai o texto da primeira parte de uma resposta de tool.
+const firstText = (r) => r.content[0].text;
+test("parseFrontmatter separa frontmatter e corpo", () => {
+    const { data, body } = parseFrontmatter("---\nname: x\ndescription: d\n---\n\n# Corpo\n");
+    assert.equal(data.name, "x");
+    assert.equal(body, "# Corpo");
+});
+test("loader carrega skills e agentes reais", () => {
+    assert.ok(entries.some((e) => e.kind === "skill" && e.id === "nestjs"));
+    assert.ok(entries.some((e) => e.kind === "agent" && e.id === "code-reviewer"));
+    // A description alimenta o ranking do `recommend_for_task`; sem ela a entrada fica invisível.
+    assert.ok(entries.every((e) => e.description.length > 0));
+});
+test("rankByMetadata prioriza a skill relevante", () => {
+    const top = rankByMetadata(entries, "criar Dockerfile multi-stage", "skill")[0];
+    assert.equal(top.entry.id, "docker");
+});
+test("searchBodies encontra trechos", () => {
+    assert.ok(searchBodies(entries, "migration").length > 0);
+    // "a" é stopword/1 letra: a consulta vira vazia e não deve devolver tudo.
+    assert.deepEqual(searchBodies(entries, "a"), []);
+});
+test("tools: list, get, erro em id inexistente, recommend", async () => {
+    const client = await connect();
+    const tools = (await client.listTools()).tools.map((t) => t.name);
+    for (const n of [
+        "list_skills",
+        "get_skill",
+        "list_agents",
+        "get_agent",
+        "search_guidelines",
+        "recommend_for_task",
+    ]) {
+        assert.ok(tools.includes(n), n);
+    }
+    assert.match(firstText(await client.callTool({ name: "list_skills", arguments: {} })), /hexagonal/);
+    assert.match(firstText(await client.callTool({ name: "get_skill", arguments: { name: "docker" } })), /Skill: docker/);
+    // Id inexistente deve ser um erro "de uso" (isError), não uma exceção do protocolo.
+    const missing = await client.callTool({ name: "get_agent", arguments: { name: "nope" } });
+    assert.equal(missing.isError, true);
+    assert.match(firstText(await client.callTool({
+        name: "recommend_for_task",
+        arguments: { task: "revisar segurança de código" },
+    })), /security-reviewer/);
+});
+test("prompts e resources expostos", async () => {
+    const client = await connect();
+    assert.ok((await client.listPrompts()).prompts.some((p) => p.name === "skill-nestjs"));
+    const res = await client.listResources();
+    assert.ok(res.resources.some((r) => r.uri === "ds9://skills/typeorm"));
+    const read = await client.readResource({ uri: "ds9://agents/test-writer" });
+    assert.match(read.contents[0].text, /Agente: test-writer/);
+});
+test("mergeServerConfig preserva outros servidores e é idempotente", () => {
+    const cursor = TARGETS.find((t) => t.id === "cursor");
+    const once = mergeServerConfig({ mcpServers: { outro: { command: "x" } } }, cursor, "linux");
+    // O servidor que o usuário já tinha ("outro") não pode ser perdido.
+    assert.deepEqual(Object.keys(once.mcpServers).sort(), ["ds9", "outro"]);
+    // Rodar de novo não pode mudar nada.
+    assert.deepEqual(mergeServerConfig(once, cursor, "linux"), once);
+    // VS Code usa `servers` + `type: stdio`; no Windows o comando passa por `cmd /c`.
+    const vscode = TARGETS.find((t) => t.id === "vscode");
+    const v = mergeServerConfig({}, vscode, "win32");
+    assert.equal(v.servers.ds9.type, "stdio");
+    assert.equal(v.servers.ds9.command, "cmd");
+});
+test("upsertAgentsBlock insere uma vez e atualiza sem duplicar", () => {
+    const once = upsertAgentsBlock("# Meu projeto\n");
+    assert.match(once, /# Meu projeto/); // conteúdo prévio preservado
+    assert.equal(upsertAgentsBlock(once), once); // segunda execução não muda nada
+    assert.equal(once.match(/ds9-mcp:start/g)?.length, 1); // bloco nunca duplica
+});
+test("runInit grava config e AGENTS.md; recusa JSON inválido", () => {
+    // Diretório temporário: o teste nunca toca em arquivos reais do usuário.
+    const dir = mkdtempSync(join(tmpdir(), "ds9-init-"));
+    const cursor = TARGETS.find((t) => t.id === "cursor");
+    const r = runInit(cursor, dir);
+    assert.ok(JSON.parse(readFileSync(r.configFile, "utf8")).mcpServers.ds9);
+    assert.match(readFileSync(r.agentsFile, "utf8"), /recommend_for_task/);
+    // Arquivo com comentário (JSONC) não pode ser sobrescrito: deve falhar com orientação.
+    writeFileSync(join(dir, ".mcp.json"), "{ // comentário\n}");
+    assert.throws(() => runInit(TARGETS[0], dir), /não é JSON puro/);
+});

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@ds9-solutions/mcp",
+  "version": "0.1.0",
+  "description": "Servidor MCP da DS9: expõe skills e subagentes oficiais para qualquer IDE/LLM com suporte a MCP",
+  "type": "module",
+  "license": "UNLICENSED",
+  "bin": {
+    "ds9-mcp": "dist/src/index.js"
+  },
+  "files": [
+    "dist",
+    "content"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "sync-content": "node scripts/sync-content.mjs",
+    "build": "tsc -p tsconfig.json",
+    "format": "prettier --write src test scripts",
+    "test": "npm run build && node --test \"dist/test/*.test.js\"",
+    "prepack": "npm run sync-content && npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "yaml": "^2.9.1",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.4",
+    "prettier": "^3.9.9",
+    "typescript": "^7.0.2"
+  }
+}