@sbissoli/mcp-surface 0.1.0

package/dist/trava.js

@@ -0,0 +1,75 @@
+/**
+ * A regra do `surface.lock.json`.
+ *
+ * Cada seção (`declarada`, `semToken`) guarda a versão do `package.json` em que
+ * foi travada e o sha256 do conteúdo. Se o medido diverge do travado:
+ *  - versão igual à da trava → FALHA: a superfície mudou sem subir a versão;
+ *  - versão diferente → FALHA pedindo para regravar (`mcp-surface travar`).
+ * O modo de escrita (`SURFACE_LOCK_ESCREVER=1`, posto pelo `mcp-surface
+ * travar`) obedece à mesma regra: ele se RECUSA a travar superfície nova sob a
+ * versão antiga. É isso que transforma a disciplina da receita de release em
+ * teste. O sha gravado também denuncia edição à mão do conteúdo.
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+import { impressaoDigital } from "./superficie.js";
+/** Variável de ambiente do modo de escrita. */
+export const VAR_ESCRITA = "SURFACE_LOCK_ESCREVER";
+const COMENTARIO = "Impressão digital da superfície (@sbissoli/mcp-surface). Não editar à mão: `npm run surface:lock` regrava, e só aceita superfície nova sob versão nova.";
+export function lerTrava(caminho) {
+    try {
+        return JSON.parse(readFileSync(caminho, "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+/** O modo de escrita está ligado neste processo? */
+export function modoEscrita() {
+    return process.env[VAR_ESCRITA] === "1";
+}
+/**
+ * Confere (e, em modo de escrita, regrava) UMA seção da trava contra o medido.
+ * Devolve o veredito em vez de lançar, para o teste mostrar a mensagem inteira:
+ * `expect(v.ok, v.mensagem).toBe(true)`.
+ */
+export function conferirSecao(caminhoDaTrava, secao, medido, versaoDoPacote, escrever = modoEscrita()) {
+    const trava = lerTrava(caminhoDaTrava);
+    const atual = trava[secao];
+    const sha = impressaoDigital(medido);
+    if (atual && impressaoDigital(atual.conteudo) !== atual.sha256) {
+        return {
+            ok: false,
+            mensagem: `surface.lock.json: a seção "${secao}" foi editada à mão (o sha256 gravado não é o do conteúdo). Restaure o arquivo e rode \`npm run surface:lock\`.`,
+        };
+    }
+    if (atual && atual.sha256 === sha) {
+        return { ok: true, mensagem: `seção "${secao}" confere (${sha.slice(0, 12)}, travada em ${atual.versao})` };
+    }
+    if (atual && atual.versao === versaoDoPacote) {
+        return {
+            ok: false,
+            mensagem: `A superfície "${secao}" MUDOU e a versão continua ${versaoDoPacote} ` +
+                `(travada ${atual.sha256.slice(0, 12)}, medida ${sha.slice(0, 12)}). ` +
+                "Quem compara o registro com o servidor só enxerga a versão: suba-a " +
+                "(`npm version <patch|minor|major> --no-git-tag-version`) e rode `npm run surface:lock`.",
+        };
+    }
+    if (!escrever) {
+        return {
+            ok: false,
+            mensagem: atual
+                ? `A superfície "${secao}" mudou junto com a versão (${atual.versao} → ${versaoDoPacote}): rode \`npm run surface:lock\` e commite o surface.lock.json.`
+                : `surface.lock.json não tem a seção "${secao}": rode \`npm run surface:lock\`.`,
+        };
+    }
+    trava[secao] = { versao: versaoDoPacote, sha256: sha, conteudo: medido };
+    const saida = { $comentario: COMENTARIO };
+    for (const nome of ["declarada", "semToken"]) {
+        const s = trava[nome];
+        if (s)
+            saida[nome] = s;
+    }
+    writeFileSync(caminhoDaTrava, `${JSON.stringify(saida, null, 2)}\n`);
+    return { ok: true, mensagem: `seção "${secao}" travada em ${versaoDoPacote} (${sha.slice(0, 12)})` };
+}
+//# sourceMappingURL=trava.js.map

package/dist/trava.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trava.js","sourceRoot":"","sources":["../src/trava.ts"],"names":[],"mappings":"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"}

package/dist/verificar.d.ts

@@ -0,0 +1,21 @@
+/**
+ * O que está NO AR é o que foi travado? Os testes provam que o CÓDIGO bate com
+ * o `surface.lock.json`; isto prova que o ENDPOINT bate. Roda no fim do deploy.
+ */
+import { type ChamadaLocal } from "./sonda.js";
+export interface OpcoesVerificar {
+    url: string;
+    caminhoDaTrava: string;
+    /** Configuração da trava que vale em produção. Padrão: `apiKeyAusente` (acesso aberto). */
+    config?: string;
+    /** Rota da seção `semToken` que corresponde a `url`. Padrão: `POST /mcp`. */
+    rota?: string;
+    /** A mesma tool local que a trava sondou; sem ela, `tools/call` não é conferido. */
+    chamada?: ChamadaLocal;
+    tentativas?: number;
+    esperaMs?: number;
+    log?: (linha: string) => void;
+}
+/** Devolve `null` quando confere; senão, a divergência da última tentativa. */
+export declare function verificarNoAr(o: OpcoesVerificar): Promise<string | null>;
+//# sourceMappingURL=verificar.d.ts.map

package/dist/verificar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verificar.d.ts","sourceRoot":"","sources":["../src/verificar.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAiB,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAI9D,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,cAAc,EAAE,MAAM,CAAC;IACvB,2FAA2F;IAC3F,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oFAAoF;IACpF,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CAC/B;AAED,+EAA+E;AAC/E,wBAAsB,aAAa,CAAC,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAqC9E"}

package/dist/verificar.js

@@ -0,0 +1,47 @@
+/**
+ * O que está NO AR é o que foi travado? Os testes provam que o CÓDIGO bate com
+ * o `surface.lock.json`; isto prova que o ENDPOINT bate. Roda no fim do deploy.
+ */
+import { capturarHttp, pedirHttp } from "./remoto.js";
+import { sondaSemToken } from "./sonda.js";
+import { impressaoDigital } from "./superficie.js";
+import { lerTrava } from "./trava.js";
+/** Devolve `null` quando confere; senão, a divergência da última tentativa. */
+export async function verificarNoAr(o) {
+    const config = o.config ?? "apiKeyAusente";
+    const rota = o.rota ?? "POST /mcp";
+    const log = o.log ?? (() => { });
+    const trava = lerTrava(o.caminhoDaTrava);
+    const declarada = trava.declarada;
+    const semToken = trava.semToken?.conteudo?.[config]?.[rota];
+    if (!declarada || !semToken) {
+        return `surface.lock.json incompleto: falta a seção declarada ou semToken["${config}"]["${rota}"].`;
+    }
+    const sonda = sondaSemToken(o.chamada).filter(p => p.method in semToken);
+    const tentativas = o.tentativas ?? 6;
+    let ultimo = "";
+    for (let t = 1; t <= tentativas; t++) {
+        const sha = impressaoDigital(await capturarHttp(o.url));
+        const divergentes = [];
+        for (const pedido of sonda) {
+            const r = await pedirHttp(o.url, pedido);
+            const responde = r.status === 200 && r.result !== undefined;
+            if (responde !== semToken[pedido.method])
+                divergentes.push(`${pedido.method} (no ar ${responde})`);
+        }
+        if (sha === declarada.sha256 && divergentes.length === 0) {
+            log(`no ar = trava: declarada ${sha.slice(0, 12)} (travada em ${declarada.versao}); ` +
+                `sem token: ${config}/${rota} confere em ${sonda.length} métodos.`);
+            return null;
+        }
+        ultimo =
+            (sha !== declarada.sha256 ? `declarada no ar ${sha.slice(0, 12)} ≠ trava ${declarada.sha256.slice(0, 12)}. ` : "") +
+                (divergentes.length ? `sem token diverge em: ${divergentes.join(", ")}.` : "");
+        log(`tentativa ${t}: ${ultimo}`);
+        // A Cloudflare serve isolates mistos por alguns segundos logo após o deploy.
+        if (t < tentativas)
+            await new Promise(r => setTimeout(r, o.esperaMs ?? 10_000));
+    }
+    return ultimo;
+}
+//# sourceMappingURL=verificar.js.map

package/dist/verificar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verificar.js","sourceRoot":"","sources":["../src/verificar.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@sbissoli/mcp-surface",
+  "version": "0.1.0",
+  "description": "Impressão digital da superfície de um servidor MCP: initialize (instructions + capabilities) + tools/resources/prompts + quem responde sem token, travados ao lado da versão — mudou sem subir a versão = build vermelho e deploy recusado; mais a conferência do endpoint no ar e o replay das versões publicadas",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SidneyBissoli/mcp-br-commons.git",
+    "directory": "packages/mcp-surface"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "mcp-surface": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "peerDependencies": {
+    "@modelcontextprotocol/server": "^2.0.0"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/server": "^2.1.0"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "surface",
+    "fingerprint",
+    "versioning",
+    "ci",
+    "mcp-registry"
+  ],
+  "author": "Sidney Bissoli <sbissoli76@gmail.com>",
+  "license": "MIT"
+}