@creativeproject/creative-plann-mcp 0.1.1 → 0.1.3

package/dist/server.js

@@ -30,6 +30,14 @@ export function createServer(client) {
             "Publicar é irreversível. Se o token não tiver permissão de publicar,",
             "deixe o post pronto e agendado e informe que a liberação é humana —",
             "não tente contornar a recusa por outro caminho.",
+            "",
+            "Depois de publicado, `get_performance` mede o resultado. Duas regras",
+            "valem em toda métrica: `null` é \"a rede não reporta isto\", diferente",
+            "de zero, que é um resultado medido; e o histórico é cumulativo — cada",
+            "leitura é o total até aquele dia, então somar leituras conta o mesmo",
+            "alcance duas vezes. Antes de dizer que o desempenho caiu, confira",
+            "`accountsWithoutInsights`: conta por reconectar derruba os totais sem",
+            "que nada tenha piorado.",
         ].join("\n"),
     });
     registerTools(server, client);

package/dist/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAEzD,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,MAA2B;IACtD,MAAM,MAAM,GAAG,IAAI,SAAS,CAC1B,EAAE,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,OAAO,EAAE,EAC5C;QACE,YAAY,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE;QAC3B,gEAAgE;QAChE,wEAAwE;QACxE,uCAAuC;QACvC,EAAE;QACF,4DAA4D;QAC5D,uEAAuE;QACvE,cAAc;QACd,YAAY,EAAE;YACZ,uEAAuE;YACvE,mDAAmD;YACnD,EAAE;YACF,yEAAyE;YACzE,0EAA0E;YAC1E,8EAA8E;YAC9E,EAAE;YACF,qEAAqE;YACrE,iEAAiE;YACjE,gFAAgF;YAChF,EAAE;YACF,sEAAsE;YACtE,qEAAqE;YACrE,iDAAiD;SAClD,CAAC,IAAI,CAAC,IAAI,CAAC;KACb,CACF,CAAC;IAEF,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAEzD,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,MAA2B;IACtD,MAAM,MAAM,GAAG,IAAI,SAAS,CAC1B,EAAE,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,OAAO,EAAE,EAC5C;QACE,YAAY,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE;QAC3B,gEAAgE;QAChE,wEAAwE;QACxE,uCAAuC;QACvC,EAAE;QACF,4DAA4D;QAC5D,uEAAuE;QACvE,cAAc;QACd,YAAY,EAAE;YACZ,uEAAuE;YACvE,mDAAmD;YACnD,EAAE;YACF,yEAAyE;YACzE,0EAA0E;YAC1E,8EAA8E;YAC9E,EAAE;YACF,qEAAqE;YACrE,iEAAiE;YACjE,gFAAgF;YAChF,EAAE;YACF,sEAAsE;YACtE,qEAAqE;YACrE,iDAAiD;YACjD,EAAE;YACF,sEAAsE;YACtE,wEAAwE;YACxE,uEAAuE;YACvE,sEAAsE;YACtE,mEAAmE;YACnE,uEAAuE;YACvE,yBAAyB;SAC1B,CAAC,IAAI,CAAC,IAAI,CAAC;KACb,CACF,CAAC;IAEF,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/tools/index.d.ts

@@ -2,7 +2,7 @@ import type { McpServer } from "@modelcontextprotocol/server";
 import type { CreativePlannClient } from "../client.js";
 /**
  * Ferramentas agrupadas por domínio: descobrir onde atuar, ver o trabalho,
- * alterá-lo. Separar por arquivo mantém cada módulo legível conforme a API
- * cresce, e deixa claro onde entra uma ferramenta nova.
+ * alterá-lo e medir o que saiu. Separar por arquivo mantém cada módulo legível
+ * conforme a API cresce, e deixa claro onde entra uma ferramenta nova.
  */
 export declare function registerTools(server: McpServer, client: CreativePlannClient): void;

package/dist/tools/index.js

@@ -1,14 +1,16 @@
 import { registerContextTools } from "./context.js";
 import { registerPlanningTools } from "./planning.js";
 import { registerAuthoringTools } from "./authoring.js";
+import { registerPerformanceTools } from "./performance.js";
 /**
  * Ferramentas agrupadas por domínio: descobrir onde atuar, ver o trabalho,
- * alterá-lo. Separar por arquivo mantém cada módulo legível conforme a API
- * cresce, e deixa claro onde entra uma ferramenta nova.
+ * alterá-lo e medir o que saiu. Separar por arquivo mantém cada módulo legível
+ * conforme a API cresce, e deixa claro onde entra uma ferramenta nova.
  */
 export function registerTools(server, client) {
     registerContextTools(server, client);
     registerPlanningTools(server, client);
     registerAuthoringTools(server, client);
+    registerPerformanceTools(server, client);
 }
 //# sourceMappingURL=index.js.map

package/dist/tools/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAExD;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,MAAiB,EAAE,MAA2B;IAC1E,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,qBAAqB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,sBAAsB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AACzC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAE5D;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,MAAiB,EAAE,MAA2B;IAC1E,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,qBAAqB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,sBAAsB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,wBAAwB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAC3C,CAAC"}

package/dist/tools/performance.d.ts

@@ -0,0 +1,13 @@
+import type { McpServer } from "@modelcontextprotocol/server";
+import type { CreativePlannClient } from "../client.js";
+/**
+ * Como o post performou depois de publicado.
+ *
+ * Duas armadilhas que as descrições precisam evitar, porque erram o relatório
+ * inteiro se passarem batido:
+ *
+ * - `null` não é zero. Zero foi medido; null é "esta rede não reporta isto".
+ * - O histórico é cumulativo: cada leitura é o total até aquele dia. Somar as
+ *   leituras contaria o mesmo alcance várias vezes.
+ */
+export declare function registerPerformanceTools(server: McpServer, client: CreativePlannClient): void;

package/dist/tools/performance.js

@@ -0,0 +1,63 @@
+import * as z from "zod/v4";
+import { COMPANY_ARG, guard, path, READ_ONLY } from "../shared.js";
+const PERIOD = z
+    .enum(["7d", "30d", "90d"])
+    .optional()
+    .describe("Janela do relatório. Padrão: 30d.");
+/**
+ * Como o post performou depois de publicado.
+ *
+ * Duas armadilhas que as descrições precisam evitar, porque erram o relatório
+ * inteiro se passarem batido:
+ *
+ * - `null` não é zero. Zero foi medido; null é "esta rede não reporta isto".
+ * - O histórico é cumulativo: cada leitura é o total até aquele dia. Somar as
+ *   leituras contaria o mesmo alcance várias vezes.
+ */
+export function registerPerformanceTools(server, client) {
+    server.registerTool("get_performance", {
+        title: "Ver desempenho da empresa",
+        description: "Resultado dos posts publicados num período: totais, variação contra o " +
+            "período anterior e o desempenho fatiado por rede, formato, campanha, " +
+            "pilar editorial e objetivo. " +
+            "Responde 'o que está funcionando?' numa chamada só. " +
+            "Atenção: `null` numa métrica significa que a rede não reporta aquilo — " +
+            "é diferente de zero, que é um resultado medido. Confira " +
+            "`accountsWithoutInsights` antes de concluir que o desempenho caiu: " +
+            "conta por reconectar derruba os totais sem que nada tenha piorado.",
+        inputSchema: z.object({ company: COMPANY_ARG, period: PERIOD }),
+        annotations: READ_ONLY,
+    }, guard(({ company, ...query }) => client.get(`/companies/${path(company)}/performance`, query)));
+    server.registerTool("list_post_performance", {
+        title: "Ranquear posts publicados",
+        description: "Posts publicados no período com as métricas de cada um, ordenáveis. " +
+            "Use `order: 'asc'` com `sort: 'engagementRate'` para achar o que NÃO " +
+            "funcionou — costuma ser mais útil que ver o topo. " +
+            "Posts ainda sem coleta ficam no fim em qualquer ordem, porque são " +
+            "ausência de dado e não resultado ruim.",
+        inputSchema: z.object({
+            company: COMPANY_ARG,
+            period: PERIOD,
+            sort: z
+                .enum(["reach", "impressions", "reactions", "engagementRate", "publishedAt"])
+                .optional()
+                .describe("Padrão: publishedAt."),
+            order: z.enum(["asc", "desc"]).optional().describe("Padrão: desc."),
+            limit: z.number().int().min(1).max(100).optional(),
+        }),
+        annotations: READ_ONLY,
+    }, guard(({ company, ...query }) => client.get(`/companies/${path(company)}/performance/posts`, query)));
+    server.registerTool("get_post_performance", {
+        title: "Ver desempenho de um post",
+        description: "Métricas de um post por rede, com o histórico de coletas desde a " +
+            "publicação — é o histórico que separa 'post fraco' de 'post ainda " +
+            "ganhando tração'. " +
+            "Os valores do histórico são CUMULATIVOS: cada leitura é o total até " +
+            "aquele dia, não o ganho do dia. Para o número atual use `current`; " +
+            "somar as leituras contaria o mesmo alcance várias vezes. " +
+            "`insightsBlockedBy` explica a ausência de métricas quando houver.",
+        inputSchema: z.object({ postId: z.string().min(1) }),
+        annotations: READ_ONLY,
+    }, guard(({ postId }) => client.get(`/posts/${path(postId)}/performance`)));
+}
+//# sourceMappingURL=performance.js.map

package/dist/tools/performance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"performance.js","sourceRoot":"","sources":["../../src/tools/performance.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAC;AAE5B,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEnE,MAAM,MAAM,GAAG,CAAC;KACb,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;KAC1B,QAAQ,EAAE;KACV,QAAQ,CAAC,mCAAmC,CAAC,CAAC;AAEjD;;;;;;;;;GASG;AACH,MAAM,UAAU,wBAAwB,CACtC,MAAiB,EACjB,MAA2B;IAE3B,MAAM,CAAC,YAAY,CACjB,iBAAiB,EACjB;QACE,KAAK,EAAE,2BAA2B;QAClC,WAAW,EACT,wEAAwE;YACxE,uEAAuE;YACvE,8BAA8B;YAC9B,sDAAsD;YACtD,yEAAyE;YACzE,0DAA0D;YAC1D,qEAAqE;YACrE,oEAAoE;QACtE,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;QAC/D,WAAW,EAAE,SAAS;KACvB,EACD,KAAK,CAAC,CAAC,EAAE,OAAO,EAAE,GAAG,KAAK,EAAE,EAAE,EAAE,CAC9B,MAAM,CAAC,GAAG,CAAC,cAAc,IAAI,CAAC,OAAO,CAAC,cAAc,EAAE,KAAK,CAAC,CAC7D,CACF,CAAC;IAEF,MAAM,CAAC,YAAY,CACjB,uBAAuB,EACvB;QACE,KAAK,EAAE,2BAA2B;QAClC,WAAW,EACT,sEAAsE;YACtE,uEAAuE;YACvE,oDAAoD;YACpD,oEAAoE;YACpE,wCAAwC;QAC1C,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;YACpB,OAAO,EAAE,WAAW;YACpB,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,CAAC;iBACJ,IAAI,CAAC,CAAC,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,gBAAgB,EAAE,aAAa,CAAC,CAAC;iBAC5E,QAAQ,EAAE;iBACV,QAAQ,CAAC,sBAAsB,CAAC;YACnC,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,eAAe,CAAC;YACnE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;SACnD,CAAC;QACF,WAAW,EAAE,SAAS;KACvB,EACD,KAAK,CAAC,CAAC,EAAE,OAAO,EAAE,GAAG,KAAK,EAAE,EAAE,EAAE,CAC9B,MAAM,CAAC,GAAG,CAAC,cAAc,IAAI,CAAC,OAAO,CAAC,oBAAoB,EAAE,KAAK,CAAC,CACnE,CACF,CAAC;IAEF,MAAM,CAAC,YAAY,CACjB,sBAAsB,EACtB;QACE,KAAK,EAAE,2BAA2B;QAClC,WAAW,EACT,mEAAmE;YACnE,oEAAoE;YACpE,oBAAoB;YACpB,sEAAsE;YACtE,qEAAqE;YACrE,2DAA2D;YAC3D,mEAAmE;QACrE,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QACpD,WAAW,EAAE,SAAS;KACvB,EACD,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,UAAU,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,CACxE,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@creativeproject/creative-plann-mcp",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Servidor MCP do Creative Plann — permite que uma IA planeje, escreva e organize posts nas redes sociais das empresas da sua organização.",
   "license": "MIT",
   "type": "module",