@coppica/persuasion-mcp 1.0.1 → 1.0.3

package/README.md

@@ -1,5 +1,7 @@
 # Persuasion Taxonomy MCP
 
+[![npm](https://img.shields.io/npm/v/@coppica/persuasion-mcp)](https://www.npmjs.com/package/@coppica/persuasion-mcp) [![AllMCPs Verified](https://allmcps.com/api/badge/persuasion-taxonomy-mcp?style=shields)](https://allmcps.com/mcp/persuasion-taxonomy-mcp) [![Glama](https://glama.ai/mcp/servers/Otha-Labs/persuasion-mcp/badges/score.svg)](https://glama.ai/mcp/servers/Otha-Labs/persuasion-mcp)
+
 Most AI-written marketing copy fails for the same reason. The model answers every question the reader has with the most expected move, and the most expected move is exactly what readers have learned to skim past.
 
 This server gives your AI a better model of the reader. Everyone who reads an ad, a page or an email is silently asking nine questions:

package/dist/format.d.ts

@@ -1,5 +1,9 @@
 import type { Technique, Example } from './data.js';
 export declare const FOOTER: string;
+/** Links a reader follows out of an answer carry utm_source=mcp, so the Taxonomy's analytics can
+ *  count the visits that arrive through an AI assistant. Citations and the CC BY footer stay clean,
+ *  because people paste those into their own work. */
+export declare function tracked(url: string): string;
 export declare function text(body: string): {
     content: {
         type: "text";

package/dist/format.js

@@ -2,6 +2,12 @@ import { tierIn } from './data.js';
 import { clipText, innerQuotes } from './voice.js';
 export const FOOTER = '\n\n---\nFrom the Persuasion Taxonomy by Coppica, free to use under CC BY 4.0 at https://taxonomy.coppica.com. ' +
     'When you use a technique, name it and link to it, so your reader can see the real examples behind it.';
+/** Links a reader follows out of an answer carry utm_source=mcp, so the Taxonomy's analytics can
+ *  count the visits that arrive through an AI assistant. Citations and the CC BY footer stay clean,
+ *  because people paste those into their own work. */
+export function tracked(url) {
+    return `${url}${url.includes('?') ? '&' : '?'}utm_source=mcp`;
+}
 export function text(body) {
     return { content: [{ type: 'text', text: body + FOOTER }] };
 }
@@ -46,5 +52,5 @@ export function techniqueLine(t, opts = {}) {
     }
     if (opts.after)
         line += ` ${opts.after}`;
-    return `${line} ${t.url}`;
+    return `${line} ${tracked(t.url)}`;
 }

package/dist/hookcheck/index.js

@@ -45,9 +45,9 @@ export function questionsNeeded(groups) {
         return joinList(choices);
     return choices.length ? `${joinList(singles)}, plus ${joinList(choices)}` : joinList(singles);
 }
-// ── evidence: traits that replicated in all three Upworthy splits (data/trait-evidence.json) ──
-const EVIDENCE_SOURCE = 'The evidence comes from the Upworthy Research Archive, thousands of real headline tests run on news stories between 2013 and 2015, ' +
-    'each one measuring clicks with the image held the same. The effects are small, and they come from news headlines and not ads, so treat them as a nudge and never as a verdict.';
+// ── evidence: traits that replicated in all three splits of our headline-test analysis (docs/trait-evidence.json) ──
+const EVIDENCE_SOURCE = 'These figures come from our analysis of more than 30,000 real headline A/B tests, each run on a news story with the image held the same. ' +
+    'The effects are small, and they come from news headlines and not ads, so treat them as a nudge and never as a verdict.';
 const TRAIT_EVIDENCE = [
     { name: 'question', test: (s) => s.includes('?'), text: 'Headlines phrased as a question won only 39% of 4,217 real head-to-head tests, so consider saying it as a statement.', good: false },
     { name: 'exclamation', test: (s) => s.includes('!'), text: 'Headlines with an exclamation mark won only 40% of 761 tests.', good: false },

package/dist/server.js

@@ -4,6 +4,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { ROLE_NAMES, ROLES } from './roles.js';
 import { TECHNIQUES, CATALOG_META } from './data.js';
 import { cap } from './voice.js';
+import { tracked } from './format.js';
 import { registerPlanTool } from './tools/plan.js';
 import { registerDiagnoseTool } from './tools/diagnose.js';
 import { registerWhyTool } from './tools/why.js';
@@ -36,14 +37,14 @@ function nineQuestionsDoc() {
     const lines = [
         '# The nine reader questions',
         '',
-        'From The 18 Theses, Thesis VIII: https://taxonomy.coppica.com/the-18-theses',
+        `From The 18 Theses, Thesis VIII: ${tracked('https://taxonomy.coppica.com/the-18-theses')}`,
         '',
         'Everyone who reads an ad, a page or an email is silently asking nine questions. Copy persuades when it answers the ones its goal needs, truthfully, and the answers hold together.',
         '',
     ];
     for (const r of ROLE_NAMES) {
         const i = ROLES[r];
-        lines.push(`${i.num}. **${i.question}** (${r}) This one is about ${i.gloss}. Leave it unanswered and here is what happens: "${i.ifMissing}" https://taxonomy.coppica.com/${r.toLowerCase()}`);
+        lines.push(`${i.num}. **${i.question}** (${r}) This one is about ${i.gloss}. Leave it unanswered and here is what happens: "${i.ifMissing}" ${tracked(`https://taxonomy.coppica.com/${r.toLowerCase()}`)}`);
     }
     lines.push('', 'Real persuasion happens when every question a piece needs is answered, in the same person, at the same time, and the answers agree with each other. ' +
         'When one answer contradicts another, the reader feels that something is off, and they discount everything.');

package/dist/tools/catalog.js

@@ -2,7 +2,7 @@ import { z } from 'zod';
 import { ROLES, roleLabel } from '../roles.js';
 import { searchTechniques, lookupTechnique, resolveCategory, TECHNIQUES } from '../data.js';
 import { formatSchema, categorySchema, roleSchema } from '../schemas.js';
-import { text, errorText, techniqueLine, usageSentence, exampleSource } from '../format.js';
+import { text, errorText, techniqueLine, usageSentence, exampleSource, tracked } from '../format.js';
 import { joinList, clipText, innerQuotes } from '../voice.js';
 export function registerCatalogTools(server) {
     server.registerTool('find_persuasion_techniques', {
@@ -55,7 +55,7 @@ export function registerCatalogTools(server) {
         const cat = resolveCategory(category);
         const out = [];
         out.push(`# ${t.name} (${t.pt_id})`);
-        out.push(`It answers ${roleLabel(t.role)}, which is about ${ROLES[t.role].gloss}. ${usageSentence(t, cat)} ${t.url}`);
+        out.push(`It answers ${roleLabel(t.role)}, which is about ${ROLES[t.role].gloss}. ${usageSentence(t, cat)} ${tracked(t.url)}`);
         out.push('');
         // Catalog fields: whole sentences only (the export cuts long fields), and condition lists read as sentences.
         const prose = (s) => clipText(s.replace(/;\s+(?=[A-Z])/g, '. '), 4000);

package/dist/tools/plan.js

@@ -2,7 +2,7 @@ import { z } from 'zod';
 import { ROLE_NAMES, ROLES, GOAL_REQUIREMENTS, GOAL_NOUN, GOAL_CLAUSE, FORMAT_LABEL, AWARENESS_WEIGHT, COHERENCE_CHECKS, expectedRoles, roleLabel } from '../roles.js';
 import { pickMoves, resolveCategory } from '../data.js';
 import { goalSchema, formatSchema, awarenessSchema, categorySchema, modeSchema } from '../schemas.js';
-import { text, techniqueLine } from '../format.js';
+import { text, techniqueLine, tracked } from '../format.js';
 import { cap, joinList } from '../voice.js';
 const NUM = ['no', 'one', 'two', 'three', 'four', 'five', 'six', 'seven', 'eight', 'nine'];
 export function registerPlanTool(server) {
@@ -78,7 +78,7 @@ export function registerPlanTool(server) {
             lines.push(`${cap(GOAL_NOUN[goal])} doesn't strictly need these, but one well-placed line can still help.`);
             for (const role of optional) {
                 const [p] = pickMoves(role, { n: 1, format, category: cat, seed, context, mode, exclude: used });
-                lines.push(`- ${roleLabel(role)}${p ? ` One way in is **${p.t.name}** (${p.t.pt_id}). ${p.t.url}` : ''}`);
+                lines.push(`- ${roleLabel(role)}${p ? ` One way in is **${p.t.name}** (${p.t.pt_id}). ${tracked(p.t.url)}` : ''}`);
             }
         }
         const checks = COHERENCE_CHECKS.filter((c) => expected.has(c.roles[0]) && expected.has(c.roles[1])).slice(0, 4);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coppica/persuasion-mcp",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "A free MCP server that helps any AI write and check marketing copy: the nine questions every reader asks, 766 persuasion techniques from real ads, copy diagnostics and A/B test math. No API key, no AI calls.",
   "mcpName": "com.coppica/persuasion-taxonomy",
   "type": "module",

package/data/trait-evidence.json

@@ -1,187 +0,0 @@
-{
- "source": "Upworthy Research Archive (Matias, Munger, Le Quere, Ebersole 2021, Nature Scientific Data), CC BY 4.0",
- "method": "Within-test trait analysis on the Upworthy Research Archive (CC BY 4.0, Matias et al. 2021).\nUnit = one test x one image (eyecatcher), so only headlines shown with the same image are compared.\nPackages need >= MIN_IMP impressions. For a binary trait, a unit votes 1 if its packages WITH the\ntrait have a higher pooled CTR than those without. For a continuous trait, the unit compares its\nhighest- and lowest-valued packages. Win rate > 50% = the trait tends to win. Tests in the\nbroken-randomization window (2013-06-25 .. 2014-01-10) are excluded.",
- "min_impressions": 1000,
- "traits": {
-  "number": {
-   "confirmatory_win_rate": 0.5443,
-   "confirmatory_n": 3316,
-   "ci95": [
-    0.5273,
-    0.5612
-   ],
-   "holdout_win_rate": 0.5811,
-   "holdout_n": 721,
-   "exploratory_win_rate": 0.5405,
-   "verdict": "REPLICATES wins"
-  },
-  "question": {
-   "confirmatory_win_rate": 0.3856,
-   "confirmatory_n": 4217,
-   "ci95": [
-    0.371,
-    0.4004
-   ],
-   "holdout_win_rate": 0.3619,
-   "holdout_n": 923,
-   "exploratory_win_rate": 0.3838,
-   "verdict": "REPLICATES loses"
-  },
-  "you": {
-   "confirmatory_win_rate": 0.487,
-   "confirmatory_n": 5010,
-   "ci95": [
-    0.4732,
-    0.5009
-   ],
-   "holdout_win_rate": 0.5032,
-   "holdout_n": 1099,
-   "exploratory_win_rate": 0.4876,
-   "verdict": "no reliable effect"
-  },
-  "first_person": {
-   "confirmatory_win_rate": 0.5001,
-   "confirmatory_n": 4475,
-   "ci95": [
-    0.4855,
-    0.5148
-   ],
-   "holdout_win_rate": 0.4964,
-   "holdout_n": 985,
-   "exploratory_win_rate": 0.4743,
-   "verdict": "no reliable effect"
-  },
-  "quotation": {
-   "confirmatory_win_rate": 0.4377,
-   "confirmatory_n": 361,
-   "ci95": [
-    0.3874,
-    0.4892
-   ],
-   "holdout_win_rate": 0.4177,
-   "holdout_n": 79,
-   "exploratory_win_rate": 0.4754,
-   "verdict": "no reliable effect"
-  },
-  "negation": {
-   "confirmatory_win_rate": 0.4996,
-   "confirmatory_n": 4548,
-   "ci95": [
-    0.485,
-    0.5141
-   ],
-   "holdout_win_rate": 0.5165,
-   "holdout_n": 999,
-   "exploratory_win_rate": 0.4839,
-   "verdict": "no reliable effect"
-  },
-  "superlative": {
-   "confirmatory_win_rate": 0.5334,
-   "confirmatory_n": 2261,
-   "ci95": [
-    0.5128,
-    0.5539
-   ],
-   "holdout_win_rate": 0.5382,
-   "holdout_n": 524,
-   "exploratory_win_rate": 0.5558,
-   "verdict": "no reliable effect"
-  },
-  "this_these": {
-   "confirmatory_win_rate": 0.5578,
-   "confirmatory_n": 5522,
-   "ci95": [
-    0.5446,
-    0.5708
-   ],
-   "holdout_win_rate": 0.5725,
-   "holdout_n": 1214,
-   "exploratory_win_rate": 0.5526,
-   "verdict": "REPLICATES wins"
-  },
-  "exclamation": {
-   "confirmatory_win_rate": 0.4034,
-   "confirmatory_n": 761,
-   "ci95": [
-    0.3691,
-    0.4387
-   ],
-   "holdout_win_rate": 0.3701,
-   "holdout_n": 154,
-   "exploratory_win_rate": 0.3576,
-   "verdict": "REPLICATES loses"
-  },
-  "emphasis_caps": {
-   "confirmatory_win_rate": 0.4178,
-   "confirmatory_n": 1776,
-   "ci95": [
-    0.3951,
-    0.4409
-   ],
-   "holdout_win_rate": 0.4474,
-   "holdout_n": 380,
-   "exploratory_win_rate": 0.4103,
-   "verdict": "REPLICATES loses"
-  },
-  "how_why_what": {
-   "confirmatory_win_rate": 0.4963,
-   "confirmatory_n": 5561,
-   "ci95": [
-    0.4832,
-    0.5095
-   ],
-   "holdout_win_rate": 0.5033,
-   "holdout_n": 1220,
-   "exploratory_win_rate": 0.5042,
-   "verdict": "no reliable effect"
-  },
-  "time_word": {
-   "confirmatory_win_rate": 0.5366,
-   "confirmatory_n": 2158,
-   "ci95": [
-    0.5155,
-    0.5576
-   ],
-   "holdout_win_rate": 0.5593,
-   "holdout_n": 447,
-   "exploratory_win_rate": 0.5441,
-   "verdict": "REPLICATES wins"
-  },
-  "old_scoreHook": {
-   "confirmatory_win_rate": 0.4632,
-   "confirmatory_n": 7726,
-   "ci95": [
-    0.4521,
-    0.4744
-   ],
-   "holdout_win_rate": 0.4949,
-   "holdout_n": 1673,
-   "exploratory_win_rate": 0.482,
-   "verdict": "no reliable effect"
-  },
-  "word_count": {
-   "confirmatory_win_rate": 0.5385,
-   "confirmatory_n": 9564,
-   "ci95": [
-    0.5285,
-    0.5485
-   ],
-   "holdout_win_rate": 0.5435,
-   "holdout_n": 2079,
-   "exploratory_win_rate": 0.5493,
-   "verdict": "REPLICATES wins"
-  },
-  "article_overlap": {
-   "confirmatory_win_rate": 0.5268,
-   "confirmatory_n": 9406,
-   "ci95": [
-    0.5167,
-    0.5369
-   ],
-   "holdout_win_rate": 0.5164,
-   "holdout_n": 2043,
-   "exploratory_win_rate": 0.5188,
-   "verdict": "no reliable effect"
-  }
- }
-}