@coppica/persuasion-mcp 1.0.2 → 1.0.4

package/dist/annotations.d.ts

@@ -0,0 +1,15 @@
+import type { ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
+/**
+ * The title and annotations every tool here shares. Each tool only reads the bundled catalog or does
+ * arithmetic: it writes, deletes and sends nothing, gives the same answer to the same input, and
+ * reaches nothing outside the catalog.
+ *
+ * The hints are spelled out on purpose. Claude's directory wants a title plus readOnlyHint or
+ * destructiveHint on every tool, and OpenAI's plugin review wants readOnlyHint, destructiveHint and
+ * openWorldHint as explicit booleans. The title goes in the annotations too, for clients on the
+ * 2025-03-26 protocol, which read it from there.
+ */
+export declare function readOnlyTool(title: string): {
+    title: string;
+    annotations: ToolAnnotations;
+};

package/dist/annotations.js

@@ -0,0 +1,16 @@
+/**
+ * The title and annotations every tool here shares. Each tool only reads the bundled catalog or does
+ * arithmetic: it writes, deletes and sends nothing, gives the same answer to the same input, and
+ * reaches nothing outside the catalog.
+ *
+ * The hints are spelled out on purpose. Claude's directory wants a title plus readOnlyHint or
+ * destructiveHint on every tool, and OpenAI's plugin review wants readOnlyHint, destructiveHint and
+ * openWorldHint as explicit booleans. The title goes in the annotations too, for clients on the
+ * 2025-03-26 protocol, which read it from there.
+ */
+export function readOnlyTool(title) {
+    return {
+        title,
+        annotations: { title, readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    };
+}

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/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,11 +2,12 @@ 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';
+import { readOnlyTool } from '../annotations.js';
 export function registerCatalogTools(server) {
     server.registerTool('find_persuasion_techniques', {
-        title: 'Find persuasion techniques',
+        ...readOnlyTool('Find persuasion techniques'),
         description: `Search the Persuasion Taxonomy, ${TECHNIQUES.length} named persuasion techniques documented from real advertising and organized by the nine reader questions they answer. ` +
             'Describe what you want the copy to do, like build trust without testimonials, create urgency without fake scarcity, handle a price objection, make an opening less generic, ' +
             'prove a claim or reframe a problem. It finds the techniques that do it. Each one comes with its name and ID, a one-line definition, a real example, ' +
@@ -19,7 +20,6 @@ export function registerCatalogTools(server) {
             category: categorySchema.optional(),
             limit: z.number().int().min(1).max(20).default(8),
         },
-        annotations: { readOnlyHint: true, openWorldHint: false, idempotentHint: true },
     }, async ({ query, question, format, category, limit }) => {
         const cat = resolveCategory(category);
         const role = question ?? null;
@@ -36,7 +36,7 @@ export function registerCatalogTools(server) {
         return text(out.join('\n'));
     });
     server.registerTool('get_persuasion_technique', {
-        title: 'Get a persuasion technique',
+        ...readOnlyTool('Get a persuasion technique'),
         description: 'Look up one persuasion technique by its ID (like PT-PRV-10000), its slug or its name. You get the full definition, why it works, when it lands and when it backfires, ' +
             'real examples from advertising, related and opposite techniques, and a link you can cite. ' +
             'Use it before you apply or recommend a technique so you get it right, and whenever someone asks what a tactic is called or how it works.',
@@ -44,7 +44,6 @@ export function registerCatalogTools(server) {
             id: z.string().min(2).max(160).describe('The PT-ID, the slug or the exact name of the technique.'),
             category: categorySchema.optional(),
         },
-        annotations: { readOnlyHint: true, openWorldHint: false, idempotentHint: true },
     }, async ({ id, category }) => {
         const t = lookupTechnique(id);
         if (!t) {
@@ -55,7 +54,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/craft.js

@@ -5,6 +5,7 @@ import { scoreClaims } from '../scorers/claim-framework.js';
 import { detectAISmell } from '../scorers/hook-framework.js';
 import { SLOTS, SLOT_INFO, checkHook, compareHooks, describeCheck, questionsNeeded, article, VERDICT_LABEL, EVIDENCE_SOURCE } from '../hookcheck/index.js';
 import { claimGateSentence, smellSentences, joinList, plural, endSentence } from '../voice.js';
+import { readOnlyTool } from '../annotations.js';
 /** Unproven superlatives the claim scorer can read as "specific" (e.g. "#1"). */
 const SUPERLATIVE = /(#\s?1\b|\bnumber one\b|\bthe best\b|\bbest[- ]in[- ]class\b|\bleading\b|\bworld'?s (best|first|most)\b|\btop[- ]rated\b|\bunmatched\b|\brevolutionary\b|\bgame[- ]chang)/i;
 const BACKED = /\b(according to|rated by|ranked by|verified|audited|source:|by g2|by capterra|survey|study|since \d{4}|\d[\d,.]*\s?(%|customers|users|reviews|stars))/i;
@@ -18,7 +19,7 @@ const briefSchema = z.object({
 }).describe('The brief. The swap test needs it to tell whether a competitor could send the line unchanged, and without it no line can pass.');
 export function registerCraftTools(server) {
     server.registerTool('check_headlines', {
-        title: 'Check and compare headlines, hooks, and subject lines',
+        ...readOnlyTool('Check and compare headlines, hooks, and subject lines'),
         description: 'Check headlines, email subject lines, ad openings, video hooks, social post openings and first lines, and compare options against each other. ' +
             'For each line it tells you whether the line does its job in that spot, meaning which of the nine reader questions it answers, and whether a competitor could send it unchanged. ' +
             'It also shows exactly what a reader sees before the cutoff, flags anything that fails outright, and brings in evidence from thousands of real headline tests. ' +
@@ -38,7 +39,6 @@ export function registerCraftTools(server) {
             follows: z.string().max(600).optional().describe('What the reader saw just before this line, like the ad before a landing page headline, or the headline or subject before a first line.'),
             awareness_level: awarenessSchema.optional(),
         },
-        annotations: { readOnlyHint: true, openWorldHint: false, idempotentHint: true },
     }, async ({ slot, lines, brief, follows, awareness_level }) => {
         const info = SLOT_INFO[slot];
         const names = lines.map((_, i) => (lines.length > 1 ? String.fromCharCode(65 + i) : 'This line'));
@@ -75,7 +75,7 @@ export function registerCraftTools(server) {
         return text(out.join('\n'));
     });
     server.registerTool('check_marketing_claims', {
-        title: 'Check marketing claims and CTAs',
+        ...readOnlyTool('Check marketing claims and CTAs'),
         description: 'Check whether marketing claims and calls to action are specific enough to believe. It catches the vague superlative, like "the best" or "#1", that readers discount on sight. ' +
             'It catches promises with no proof behind them and results with no mechanism, and it flags the generic buttons everyone uses, like "Learn more" and "Get started". ' +
             'Then it tells you how to fix each one. Use it when you write or review claims like "results in days", "trusted by thousands" or "the #1 tool", and for any button text. ' +
@@ -87,7 +87,6 @@ export function registerCraftTools(server) {
                 context: z.string().max(1500).optional().describe('For a claim in the body, the paragraph around it, so a mechanism named nearby still counts.'),
             })).min(1).max(30),
         },
-        annotations: { readOnlyHint: true, openWorldHint: false, idempotentHint: true },
     }, async ({ claims }) => {
         const out = [`# ${plural(claims.length, 'claim')}, checked`];
         // Headline claims go through the hook check's facts; the old headline scorer did not predict winners.

package/dist/tools/diagnose.js

@@ -6,6 +6,7 @@ import { text, techniqueLine } from '../format.js';
 import { scoreFlow } from '../scorers/flow-framework.js';
 import { checkHook, describeCheck, VERDICT_LABEL } from '../hookcheck/index.js';
 import { flowGateSentence, joinList, plural } from '../voice.js';
+import { readOnlyTool } from '../annotations.js';
 export const OPENING_SLOT = {
     ad: 'ad_opening', landing_page: 'landing_page_headline', sales_letter: 'sales_letter_headline', email: 'first_line',
     email_subject: 'email_subject', social_post: 'social_post_open', video_script: 'video_hook', headline: 'landing_page_headline',
@@ -45,7 +46,7 @@ const normText = (s) => s.toLowerCase().replace(/[‘’]/g, "'").replace(/[“
 const STATUS_RANK = { missing: 0, partial: 1, clear: 2 };
 export function registerDiagnoseTool(server) {
     server.registerTool('diagnose_marketing_copy', {
-        title: 'Diagnose marketing copy (roast / review)',
+        ...readOnlyTool('Diagnose marketing copy (roast / review)'),
         description: "Review, critique or roast any piece of marketing copy, whether it's an ad, a landing page, an email, a sales page, a social post or a script, and find out why it might not persuade. " +
             'Before you call it, read the copy and label each line with the one reader question it mainly answers, quoting the words exactly. Those labels go in the moves array. ' +
             'You get back which of the nine questions the copy answers for its goal, which it answers weakly and which it skips, along with the biggest gap and what readers do when it is missing. ' +
@@ -73,7 +74,6 @@ export function registerDiagnoseTool(server) {
                 proof: z.string().max(400).optional(),
             }).optional().describe('The brief, if you have it: the brand, product, offer, audience and proof. With it, the opening line gets the swap test, which asks whether a competitor could send it unchanged.'),
         },
-        annotations: { readOnlyHint: true, openWorldHint: false, idempotentHint: true },
     }, async ({ copy, goal, format, moves, awareness_level, category, headline, persuasion_mode, brief }) => {
         const cat = resolveCategory(category);
         const expected = expectedRoles(goal);

package/dist/tools/plan.js

@@ -2,12 +2,13 @@ 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';
+import { readOnlyTool } from '../annotations.js';
 const NUM = ['no', 'one', 'two', 'three', 'four', 'five', 'six', 'seven', 'eight', 'nine'];
 export function registerPlanTool(server) {
     server.registerTool('plan_marketing_copy', {
-        title: 'Plan marketing copy (the nine reader questions)',
+        ...readOnlyTool('Plan marketing copy (the nine reader questions)'),
         description: "Plan any piece of marketing copy before you write it, whether it's an ad, a landing page, a sales page or sales letter, an email, a subject line, a social post, a headline or a video script. " +
             'Give it the goal, the reader and the offer, and it tells you which of the nine questions every reader silently asks this piece has to answer, which ones deserve the most words for this reader, ' +
             'and a few ways to answer each one, drawn from real advertising and linked to the Persuasion Taxonomy. One option is always the established move and the rest are less expected, ' +
@@ -23,7 +24,6 @@ export function registerPlanTool(server) {
             persuasion_mode: modeSchema,
             options_per_question: z.number().int().min(2).max(6).default(4).describe('How many ways to answer each question you want to see. The default is 4.'),
         },
-        annotations: { readOnlyHint: true, openWorldHint: false, idempotentHint: true },
     }, async ({ goal, format, audience, offer, awareness_level, category, persuasion_mode, options_per_question }) => {
         const cat = resolveCategory(category);
         const awareness = awareness_level ?? 'problem_aware';
@@ -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/dist/tools/testing.js

@@ -4,13 +4,14 @@ import { roleSchema } from '../schemas.js';
 import { text, errorText } from '../format.js';
 import { sampleSizePerArm, compare, srmPValue } from '../stats.js';
 import { joinList, plural } from '../voice.js';
+import { readOnlyTool } from '../annotations.js';
 const pct = (v, d = 2) => `${(v * 100).toFixed(d)}%`;
 const points = (v) => `${(v * 100).toFixed(2)}`;
 const fmt = (n) => n.toLocaleString('en-US');
 const pValue = (p) => (p < 0.0001 ? 'below 0.0001' : p.toFixed(4));
 export function registerTestingTools(server) {
     server.registerTool('plan_ab_test', {
-        title: 'Plan an A/B test',
+        ...readOnlyTool('Plan an A/B test'),
         description: 'Plan an A/B test for marketing copy. Give it the current conversion rate, the smallest lift worth detecting and the daily traffic, ' +
             'and it tells you how many visitors each version needs and how many days to run. It also frames the test as two different answers to the same reader question, ' +
             'so the result teaches you something you can reuse, and not just that "B won". ' +
@@ -26,7 +27,6 @@ export function registerTestingTools(server) {
             version_a: z.string().max(600).optional().describe('How version A answers it.'),
             version_b: z.string().max(600).optional().describe('How version B answers it.'),
         },
-        annotations: { readOnlyHint: true, openWorldHint: false, idempotentHint: true },
     }, async (a) => {
         const base = a.baseline_conversion_rate_percent / 100;
         const lift = a.minimum_detectable_lift_percent / 100;
@@ -67,7 +67,7 @@ export function registerTestingTools(server) {
         return text(out.join('\n'));
     });
     server.registerTool('read_ab_test_result', {
-        title: 'Read an A/B test result',
+        ...readOnlyTool('Read an A/B test result'),
         description: "Read the result of an A/B test. You get each version's conversion rate and lift, whether the difference is statistically significant, the confidence interval, " +
             'and the chance each version really beats the original. It also warns you about the things that make a test result lie. Those include too few conversions, ' +
             "traffic that didn't split the way it should (a sample ratio mismatch), stopping the moment it looked good, and testing too many versions at once. " +
@@ -82,7 +82,6 @@ export function registerTestingTools(server) {
             confidence: z.number().min(0.8).max(0.999).default(0.95),
             question: roleSchema.optional().describe('The reader question the versions answered in different ways.'),
         },
-        annotations: { readOnlyHint: true, openWorldHint: false, idempotentHint: true },
     }, async ({ versions, intended_split, confidence, question }) => {
         if (versions.some((v) => v.conversions > v.visitors))
             return errorText('One of the versions has more conversions than visitors, so check the numbers.');

package/dist/tools/why.js

@@ -3,9 +3,10 @@ import { ROLES, SYMPTOMS, SYMPTOM_MAP, roleLabel } from '../roles.js';
 import { pickMoves, resolveCategory } from '../data.js';
 import { formatSchema, categorySchema, modeSchema } from '../schemas.js';
 import { text, techniqueLine } from '../format.js';
+import { readOnlyTool } from '../annotations.js';
 export function registerWhyTool(server) {
     server.registerTool('explain_why_not_converting', {
-        title: 'Explain why marketing is not converting',
+        ...readOnlyTool('Explain why marketing is not converting'),
         description: "Work out why an ad, a landing page, an email or a whole funnel isn't converting. Start from what you can see. " +
             "Maybe people don't click (a low CTR), or they click and bounce, or they read and don't buy. Maybe they abandon the checkout or the form, the leads never buy, " +
             "customers buy once and leave, or emails don't get opened or get opened and nobody clicks. " +
@@ -21,7 +22,6 @@ export function registerWhyTool(server) {
             category: categorySchema.optional(),
             persuasion_mode: modeSchema,
         },
-        annotations: { readOnlyHint: true, openWorldHint: false, idempotentHint: true },
     }, async ({ symptom, format, details, category, persuasion_mode }) => {
         const info = SYMPTOM_MAP[symptom];
         const cat = resolveCategory(category);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@coppica/persuasion-mcp",
-  "version": "1.0.2",
-  "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.",
+  "version": "1.0.4",
+  "description": "A free MCP server that helps any AI write and check marketing copy: the nine questions every reader asks, 767 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",
   "bin": {