@coppica/persuasion-mcp 1.0.1

package/dist/tools/plan.js

@@ -0,0 +1,99 @@
+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 { cap, joinList } from '../voice.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)',
+        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, ' +
+            'because left to itself a model answers every question with the move everyone else makes, and readers have learned to skim past it. ' +
+            "So call it before you draft, even when you're sure you know how to write the piece, and when the draft is done, check it with diagnose_marketing_copy.",
+        inputSchema: {
+            goal: goalSchema,
+            format: formatSchema,
+            audience: z.string().min(2).max(600).describe('Who will read it, as specifically as you can put it: their role, their situation and what they already believe.'),
+            offer: z.string().min(2).max(600).describe("What you're selling or asking for, and the main promise."),
+            awareness_level: awarenessSchema.optional(),
+            category: categorySchema.optional(),
+            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';
+        const weight = AWARENESS_WEIGHT[awareness];
+        const expected = expectedRoles(goal);
+        const reqs = GOAL_REQUIREMENTS[goal];
+        const seed = `${goal}|${format}|${audience}|${offer}|${cat ?? ''}`;
+        const context = `${audience} ${offer}`;
+        const mode = persuasion_mode;
+        const used = new Set();
+        const piece = FORMAT_LABEL[format].replace(/^an? /, '');
+        const lines = [];
+        lines.push(`# Copy plan: ${FORMAT_LABEL[format]} that ${GOAL_CLAUSE[goal]}`);
+        lines.push(`The reader: ${audience}`);
+        lines.push(`The offer: ${offer}`);
+        lines.push('');
+        lines.push(awareness_level
+            ? weight.note
+            : `${weight.note} This plan assumes the reader is at that stage, so pass awareness_level if you know otherwise.`);
+        if (category && !cat)
+            lines.push(`There isn't enough data on "${category}" to compare against, so this plan skips the category comparison.`);
+        lines.push('');
+        lines.push(`Every reader is silently asking nine questions. For ${GOAL_NOUN[goal]}, this ${piece} has to answer ${reqs.length === 9 ? 'all nine' : `${NUM[reqs.length]} of them`}, ` +
+            'roughly in the order below, and the ones marked as a priority deserve the most words for this reader.');
+        lines.push(`Under each question you'll find a few ways to answer it, ranked for this brief in ${mode} mode. Pick the one that fits this reader and this offer best, ` +
+            "and make sure at least one of your picks is a less expected move, because that's where the copy stops sounding like everyone else in the category. " +
+            'To see real examples of a technique, and when it backfires, call get_persuasion_technique with its ID.');
+        const either = reqs.filter((req) => req.length > 1);
+        for (const role of ROLE_NAMES) {
+            if (!expected.has(role))
+                continue;
+            const info = ROLES[role];
+            const alt = either.find((req) => req.includes(role));
+            lines.push('');
+            lines.push(`## ${info.num}. ${info.question} (${role})`);
+            let body = `Leave it unanswered and this is what happens: "${info.ifMissing}"`;
+            if (weight.heavy.includes(role))
+                body += ' This is a priority for this reader, so give it more words than most.';
+            if (alt)
+                body += ` You can answer this one or ${joinList(alt.filter((r) => r !== role).map((r) => `"${ROLES[r].question}"`), 'or')}, and one of them is enough.`;
+            lines.push(body);
+            const picks = pickMoves(role, { n: options_per_question, format, category: cat, seed, context, mode, exclude: used });
+            for (const p of picks) {
+                used.add(p.t.slug);
+                lines.push(techniqueLine(p.t, { category: cat, kind: p.kind === 'established' ? 'established' : 'less expected', example: false }));
+            }
+        }
+        const optional = ROLE_NAMES.filter((r) => !expected.has(r));
+        if (optional.length) {
+            lines.push('');
+            lines.push('## The other questions');
+            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}` : ''}`);
+            }
+        }
+        const checks = COHERENCE_CHECKS.filter((c) => expected.has(c.roles[0]) && expected.has(c.roles[1])).slice(0, 4);
+        if (checks.length) {
+            lines.push('');
+            lines.push('## Make the answers agree');
+            lines.push("Readers hold each answer up against the others. When two don't match, they can't always say why, but they feel that something is off, " +
+                'and everything else loses weight. Before you finish, ask yourself these questions.');
+            for (const c of checks)
+                lines.push(`- ${c.check}`);
+        }
+        lines.push('');
+        lines.push('## Then write it');
+        lines.push("Choose one move for each question. The less expected choices are where the copy stops sounding like everyone else, so don't play every one safe, " +
+            'and keep every claim true. When the draft is done, label each line with the question it answers and run diagnose_marketing_copy before you show it to anyone.');
+        return text(lines.join('\n'));
+    });
+}

package/dist/tools/testing.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerTestingTools(server: McpServer): void;

package/dist/tools/testing.js

@@ -0,0 +1,145 @@
+import { z } from 'zod';
+import { ROLES } from '../roles.js';
+import { roleSchema } from '../schemas.js';
+import { text, errorText } from '../format.js';
+import { sampleSizePerArm, compare, srmPValue } from '../stats.js';
+import { joinList, plural } from '../voice.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',
+        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". ' +
+            'Use it when someone asks how long to run a test, how much traffic they need, whether a test is worth running, or what to test next.',
+        inputSchema: {
+            baseline_conversion_rate_percent: z.number().positive().lt(100).describe('The current conversion rate, in percent, so 3 means 3% and 0.8 means 0.8%.'),
+            minimum_detectable_lift_percent: z.number().positive().max(500).describe('The smallest relative lift worth detecting, in percent. 20 means a 20% lift, like going from 3% to 3.6%.'),
+            daily_visitors: z.number().positive().describe('How many visitors a day enter the test, across all versions.'),
+            versions: z.number().int().min(2).max(6).default(2).describe('How many versions, counting the original.'),
+            confidence: z.number().min(0.8).max(0.999).default(0.95),
+            power: z.number().min(0.5).max(0.99).default(0.8),
+            question: roleSchema.optional().describe('The reader question both versions answer, each in its own way.'),
+            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;
+        if (base * (1 + lift) >= 1)
+            return errorText('That lift would push the conversion rate past 100%, so use a smaller lift.');
+        const comparisons = a.versions - 1;
+        const alpha = (1 - a.confidence) / comparisons;
+        const perArm = sampleSizePerArm(base, lift, alpha, a.power);
+        const total = perArm * a.versions;
+        const days = Math.ceil(total / a.daily_visitors);
+        const weeks = Math.max(1, Math.ceil(days / 7));
+        const out = [];
+        out.push(`# A/B test plan for ${a.versions} versions`);
+        out.push(`To detect a ${pct(lift, 0)} lift on a ${pct(base)} conversion rate, which means going from ${pct(base)} to ${pct(base * (1 + lift))}, ` +
+            `at ${pct(a.confidence, 0)} confidence and ${pct(a.power, 0)} power${comparisons > 1 ? `, corrected for ${comparisons} comparisons` : ''}, ` +
+            `you need ${fmt(perArm)} visitors for each version, or ${fmt(total)} in total.`);
+        out.push(`At ${fmt(a.daily_visitors)} visitors a day, that takes about ${plural(days, 'day')}. Run it in whole weeks, so ${plural(weeks, 'week')}, ` +
+            'and weekdays and weekends both get counted.');
+        out.push(`Expect about ${fmt(Math.round(perArm * base))} conversions for each version. Decide now when you'll stop, and don't stop early because one day looks good.`);
+        if (days > 56) {
+            out.push('');
+            out.push('That is more than eight weeks, which is a long time to wait, and you have three ways to shorten it. You can test a bigger difference, meaning two genuinely different answers ' +
+                'to a reader question instead of a change in wording. You can test a step with more traffic, like clicks instead of purchases. ' +
+                `Or you can accept that you'll only catch a bigger lift, since a ${pct(Math.min(lift * 2, 4), 0)} lift needs roughly a quarter of the traffic.`);
+        }
+        out.push('');
+        out.push('## Make the test teach you something');
+        if (a.question) {
+            const r = a.question;
+            out.push(`Your hypothesis is that for this audience, ${a.version_b ? `"${a.version_b}"` : 'version B'} is a better answer to "${ROLES[r].question}" than ${a.version_a ? `"${a.version_a}"` : 'version A'}. ` +
+                'Change only that answer between the versions. Whichever wins tells you something about these readers that carries over to your next ad, page and email.');
+        }
+        else {
+            out.push('Pick one reader question and test two different answers to it, like proof by demonstration against proof by testimonial, and keep everything else the same. ' +
+                `"Version B won" teaches you nothing. "For these buyers, a demonstration answers '${ROLES.PROVE.question}' better than a testimonial" carries over to everything you write next.`);
+        }
+        out.push('When the test is done, read the result with read_ab_test_result.');
+        return text(out.join('\n'));
+    });
+    server.registerTool('read_ab_test_result', {
+        title: '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. " +
+            "So use it whenever someone shares test numbers, or asks \"did my test win?\", \"is this significant?\", \"which version won?\" or \"should I keep it running?\"",
+        inputSchema: {
+            versions: z.array(z.object({
+                name: z.string().min(1).max(120),
+                visitors: z.number().int().positive(),
+                conversions: z.number().int().min(0),
+            })).min(2).max(6).describe('Each version with its visitors and conversions. Put the original, the control, first.'),
+            intended_split: z.array(z.number().positive()).optional().describe('How you meant to split the traffic, like [50, 50]. The default is an even split.'),
+            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.');
+        if (intended_split && intended_split.length !== versions.length)
+            return errorText('intended_split needs one share for each version.');
+        const [ctrl, ...rest] = versions;
+        const comparisons = rest.length;
+        const alpha = (1 - confidence) / comparisons;
+        const out = [];
+        out.push(`# A/B test result for ${versions.length} versions, with "${ctrl.name}" as the original`);
+        out.push(`"${ctrl.name}" converted ${fmt(ctrl.conversions)} of ${fmt(ctrl.visitors)} visitors, or ${pct(ctrl.conversions / ctrl.visitors)}.`);
+        let anyWinner = false;
+        for (const v of rest) {
+            const c = compare(ctrl.conversions, ctrl.visitors, v.conversions, v.visitors, alpha);
+            const sig = c.p < alpha;
+            if (sig && c.diff > 0)
+                anyWinner = true;
+            const verdict = sig
+                ? (c.diff > 0 ? "That's a statistically significant win." : "That's a statistically significant loss.")
+                : "That difference isn't statistically significant yet.";
+            out.push('');
+            out.push(`"${v.name}" converted ${fmt(v.conversions)} of ${fmt(v.visitors)}, or ${pct(c.rateB)}, which is a ${pct(Math.abs(c.relLift), 1)} ${c.relLift >= 0 ? 'lift' : 'drop'}. ${verdict} ` +
+                `The p-value is ${pValue(c.p)}${comparisons > 1 ? `, against a threshold of ${alpha.toFixed(4)} after correcting for ${comparisons} comparisons` : ''}. ` +
+                `At ${pct(confidence, 0)} confidence${comparisons > 1 ? ' (corrected)' : ''}, the true difference sits somewhere between ${points(c.ciLow)} and ${points(c.ciHigh)} percentage points, ` +
+                `and the chance it really beats the original is ${pct(c.probBBetter, 0)}.`);
+        }
+        const warnings = [];
+        const shares = intended_split ?? versions.map(() => 1);
+        const srm = srmPValue(versions.map((v) => v.visitors), shares);
+        if (srm < 0.001) {
+            warnings.push(`The traffic didn't split the way you intended, which is called a sample ratio mismatch (p-value ${pValue(srm)}). ` +
+                "It means something in the assignment or the tracking is broken, so don't trust this result until you find it.");
+        }
+        const lowConv = versions.filter((v) => v.conversions < 30);
+        if (lowConv.length) {
+            warnings.push(`${joinList(lowConv.map((v) => `"${v.name}"`))} ${lowConv.length === 1 ? 'has' : 'have'} fewer than 30 conversions. ` +
+                'Results that small swing wildly, so keep the test running to the sample you planned.');
+        }
+        if (anyWinner)
+            warnings.push("Big lifts from small tests usually shrink once you roll them out. It's called the winner's curse, so expect less than the lift you measured.");
+        warnings.push('And if you checked the results over and over and stopped when they looked good, the p-value overstates how sure you can be. Stop at the sample size you planned with plan_ab_test.');
+        out.push('');
+        out.push('## Before you act');
+        out.push(warnings.join(' '));
+        out.push('');
+        out.push('## What you learned');
+        if (question) {
+            const r = question;
+            out.push(anyWinner
+                ? `Write it down. For this audience, the winning answer to "${ROLES[r].question}" beat the original. Use it in your next ad, page and email, and test a new challenger against it.`
+                : `These versions answer "${ROLES[r].question}" in different ways, and so far there's no reliable difference between them. Either both answers work about equally well for this audience, ` +
+                    'or the test needs more traffic. Next time, try an answer that is more different.');
+        }
+        else {
+            out.push('Name the reader question the versions answered differently, and the technique each one used. That turns this result into a rule you can reuse, instead of a one-off winner.');
+        }
+        out.push('To find your next challenger, use find_persuasion_techniques.');
+        return text(out.join('\n'));
+    });
+}

package/dist/tools/why.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerWhyTool(server: McpServer): void;

package/dist/tools/why.js

@@ -0,0 +1,63 @@
+import { z } from 'zod';
+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';
+export function registerWhyTool(server) {
+    server.registerTool('explain_why_not_converting', {
+        title: '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. " +
+            "Whatever the symptom, you get back the reader questions most likely going unanswered, what to check in the copy first, and the problems copy can't fix that you should rule out, " +
+            'along with techniques to try and the test that would confirm the diagnosis. ' +
+            "So use it whenever someone says their marketing \"isn't working\", \"isn't converting\" or \"isn't selling\", or asks why results dropped.",
+        inputSchema: {
+            symptom: z.enum(SYMPTOMS).describe('What you can see happening. Use low_click_through when people see it and don\'t click, high_bounce when they click and leave fast, reads_but_no_action when they read and don\'t convert, ' +
+                'starts_but_abandons when they abandon the checkout or form, leads_dont_buy when signups never buy, buys_once_no_return for refunds, churn and no repeat orders, ' +
+                'low_open_rate when emails don\'t get opened, and opens_no_clicks when they get opened but not clicked.'),
+            format: formatSchema.optional(),
+            details: z.string().max(2000).optional().describe('Anything you know: the numbers, what changed recently, the offer and the audience.'),
+            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);
+        const out = [];
+        out.push(`# Why it isn't converting: ${info.label}`);
+        if (details)
+            out.push(`The situation: ${details}`);
+        out.push('');
+        out.push(`Before you touch the copy, rule out the things copy can't fix. ${info.ruleOutFirst}`);
+        out.push('');
+        out.push('If those check out, the problem is most likely a question the copy leaves unanswered. Here are the suspects, most likely first.');
+        info.suspects.forEach((s, i) => {
+            out.push('');
+            if (s.role === 'COHERENCE') {
+                out.push(`## ${i + 1}. The answers don't agree with each other`);
+                out.push(`${s.why} ${s.check}`);
+                return;
+            }
+            const role = s.role;
+            out.push(`## ${i + 1}. ${roleLabel(role)}`);
+            out.push(`Leave it unanswered and this is what happens: "${ROLES[role].ifMissing}" ${s.why} ${s.check}`);
+            if (i < 2) {
+                out.push('Here are two ways to answer it.');
+                for (const p of pickMoves(role, { n: 2, format: format ?? null, category: cat, seed: `${symptom}|${details ?? ''}`, context: `${info.label} ${s.check} ${details ?? ''}`, mode: persuasion_mode })) {
+                    out.push(techniqueLine(p.t, { category: cat, kind: p.kind === 'established' ? 'established' : 'less expected', example: false }));
+                }
+            }
+        });
+        const top = info.suspects.find((s) => s.role !== 'COHERENCE');
+        out.push('');
+        out.push('## Confirm it with a test');
+        out.push(top
+            ? `Keep everything else the same and test two versions that answer "${ROLES[top.role].question}" in different ways, for example the established move above against the less expected one. ` +
+                'If this was the gap, the version that answers it better will move the number. Size the test with plan_ab_test.'
+            : 'Fix the mismatch on one side only and test it against the current version. Size the test with plan_ab_test.');
+        out.push('If you have the copy itself, label each line and run diagnose_marketing_copy for a line-by-line read.');
+        return text(out.join('\n'));
+    });
+}

package/dist/voice.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Plain-English rendering for everything the scorers report.
+ *
+ * The scorers in src/scorers/ are copied from Coppica and stay in sync with it, so their own
+ * messages are left alone. Nothing they say reaches a model directly: it goes through here first,
+ * and comes out as full sentences in the voice of a working copywriter. Every tool output is a
+ * sample of the writing we want people to produce, so it has to read like good writing itself.
+ */
+import type { FlowScore } from './scorers/flow-framework.js';
+type FlowGateResult = FlowScore['gates'][number];
+export declare const cap: (s: string) => string;
+/** "a", "a and b", "a, b and c" */
+export declare function joinList(items: string[], conj?: string): string;
+export declare const plural: (n: number, one: string, many?: string) => string;
+/** Add a period unless the sentence already ends in one, including inside a closing quote ('..."Is this for me?"'). */
+export declare const endSentence: (s: string) => string;
+/**
+ * Shorten text to about n characters at the end of a sentence where possible, otherwise at a word,
+ * never mid-word. Text the catalog export already cut (ending in …) is pulled back the same way.
+ */
+export declare function clipText(s: string, n: number): string;
+/** Catalog text quoted inside our own double quotes: turn its inner double quotes into single ones. */
+export declare const innerQuotes: (s: string) => string;
+/** detectAISmell() violations -> stock words found, and one sentence per machine-written pattern. */
+export declare function readSmell(violations: string[]): {
+    words: string[];
+    patterns: string[];
+};
+export declare function smellSentences(violations: string[]): string[];
+/** One failing or warning flow gate -> what a good editor would tell the writer. */
+export declare function flowGateSentence(g: FlowGateResult): string | null;
+export declare function claimGateSentence(name: string, claim: string, type: 'cta' | 'body_claim'): string | null;
+export {};

package/dist/voice.js

@@ -0,0 +1,139 @@
+export const cap = (s) => (s ? s[0].toUpperCase() + s.slice(1) : s);
+/** "a", "a and b", "a, b and c" */
+export function joinList(items, conj = 'and') {
+    if (items.length <= 1)
+        return items[0] ?? '';
+    return `${items.slice(0, -1).join(', ')} ${conj} ${items[items.length - 1]}`;
+}
+export const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+/** Add a period unless the sentence already ends in one, including inside a closing quote ('..."Is this for me?"'). */
+export const endSentence = (s) => (/[.!?…]["')\]]?$/.test(s.trim()) ? s.trim() : `${s.trim()}.`);
+/**
+ * Shorten text to about n characters at the end of a sentence where possible, otherwise at a word,
+ * never mid-word. Text the catalog export already cut (ending in …) is pulled back the same way.
+ */
+export function clipText(s, n) {
+    const t = s.trim();
+    const cps = Array.from(t);
+    const cutByExport = t.endsWith('…');
+    if (cps.length <= n && !cutByExport)
+        return t;
+    const cut = cps.length > n ? cps.slice(0, n).join('') : t.slice(0, -1);
+    const ends = [...cut.matchAll(/[.!?]["')\]]?(?=\s)/g)];
+    const last = ends[ends.length - 1];
+    if (last && last.index + last[0].length >= cut.length * 0.4)
+        return cut.slice(0, last.index + last[0].length);
+    const space = cut.lastIndexOf(' ');
+    return `${(space > 0 ? cut.slice(0, space) : cut).replace(/[\s,;:(\[]+$/, '')}…`;
+}
+/** Catalog text quoted inside our own double quotes: turn its inner double quotes into single ones. */
+export const innerQuotes = (s) => s.replace(/["“”]/g, "'");
+// ── machine-written phrasing ─────────────────────────────────────────────────
+const PATTERN_TEXT = {
+    em_dash_reversal: 'The "X, then a dash, then it\'s Y" reversal is one of the most recognizable machine-written moves. Use a period and make the point straight.',
+    not_just_but: '"It\'s not just X, it\'s Y" is one of the most recognizable machine-written lines. Say the one thing you mean and let it stand.',
+    more_than_just: '"More than just" is filler. Cut it and say what the thing actually is.',
+    in_the_world_of: '"In the world of..." is throat-clearing. Skip the setup and make the claim.',
+    tripled_adjectives: 'Three adjectives stacked on one noun, like "fast, simple, and powerful platform", is corporate boilerplate. Keep the one claim you can prove.',
+    hope_this_helps: '"Hope this helps" is chatbot filler. Cut it.',
+    absolutely_great_question: 'Words like "absolutely" and "great question" are chatbot filler. Get to the point.',
+};
+/** detectAISmell() violations -> stock words found, and one sentence per machine-written pattern. */
+export function readSmell(violations) {
+    const words = [];
+    const patterns = [];
+    for (const v of violations) {
+        const w = v.match(/^Banned word\/phrase: "(.+)"$/);
+        if (w) {
+            words.push(w[1]);
+            continue;
+        }
+        const name = v.split(':')[0];
+        patterns.push(PATTERN_TEXT[name] ?? v.slice(name.length + 1).trim());
+    }
+    return { words, patterns };
+}
+export function smellSentences(violations) {
+    const { words, patterns } = readSmell(violations);
+    const out = [];
+    if (words.length) {
+        const quoted = joinList(words.slice(0, 5).map((w) => `"${w}"`));
+        out.push(`Readers now link ${words.length === 1 ? `the word ${quoted}` : `words like ${quoted}`} with machine-written copy, and they skim past ${words.length === 1 ? 'it' : 'them'}. ` +
+            `Use the plain word you would say out loud.`);
+    }
+    return [...out, ...patterns];
+}
+// ── flow (craft and rhythm) ──────────────────────────────────────────────────
+const BAND_TEXT = [
+    [/no short punches/, 'There isn\'t one short, punchy sentence in it.'],
+    [/long sentences/, 'Almost nothing runs long enough to build momentum.'],
+    [/medium length/, 'Nearly every sentence is medium length, and that is what makes it feel monotonous.'],
+];
+/** One failing or warning flow gate -> what a good editor would tell the writer. */
+export function flowGateSentence(g) {
+    const fail = g.status === 'fail';
+    switch (g.name) {
+        case 'ai_smell_lexicon':
+            return smellSentences((g.detail ?? '').split('; ').filter(Boolean)).join(' ');
+        case 'em_dash_density':
+            return 'There are more em dashes than a person would use in this much copy. Most of them want to be periods.';
+        case 'negative_parallelism_cap':
+            return 'The copy leans on "it\'s not X, it\'s Y" more than once, and readers now hear that as machine-written. Keep the stronger half and say it plainly.';
+        case 'triad_density':
+            return 'Several lines stack three adjectives on an abstract noun. People rarely talk that way, so keep the one that is true and specific.';
+        case 'burstiness':
+            return fail
+                ? 'The sentences all run about the same length, and that makes the copy drone. Put a three-word line next to a long one that builds.'
+                : 'The sentence lengths are still fairly even. Vary them more.';
+        case 'paragraph_variance':
+            return 'The paragraphs are all about the same size. Let a one-line paragraph land between the longer ones.';
+        case 'rhythmic_contrast':
+            return 'In places, several sentences in a row land at the same length. Break the run with a short punch or a longer build.';
+        case 'band_distribution': {
+            const found = BAND_TEXT.filter(([re]) => re.test(g.detail ?? '')).map(([, t]) => t);
+            return found.length ? `${found.join(' ')} Mix in a few of each.` : 'The mix of short and long sentences is off. Vary it.';
+        }
+        case 'consecutive_band':
+            return 'Three or more sentences in a row land at the same length, and that is what makes copy sound flat. Break the run.';
+        case 'opening_uniformity':
+            return 'Most of the paragraphs start the same way. Vary how they open.';
+        case 'bucket_brigade_density':
+            return 'Long copy needs small phrases that pull the reader on to the next line, like "Here\'s the thing" or "But there\'s a catch." This has too few of them.';
+        case 'threading_ratio':
+            return fail
+                ? 'The sentences read like a list. Each one should pick up where the last one left off, with a pronoun, a word like "so" or "but", or a key word carried over.'
+                : 'A few sentences stand alone when they should pull the reader forward.';
+        case 'closing_recap':
+            return 'The last paragraph mostly repeats what came before. Cut the recap and end on your strongest line.';
+        default:
+            return g.detail ? g.detail.replace(/\s+—\s+/g, '. ') : null;
+    }
+}
+// ── claims and buttons ───────────────────────────────────────────────────────
+export function claimGateSentence(name, claim, type) {
+    const text = claim.trim();
+    const first = text.split(/\s+/)[0] ?? '';
+    const words = text.split(/\s+/).filter(Boolean).length;
+    switch (name) {
+        case 'generic_button_text':
+            return `"${text}" is the button everyone uses. Say what they get instead, like "Save my seat", "Book my audit" or "Send me the guide".`;
+        case 'first_person_or_outcome':
+            return 'A button works harder in the reader\'s own voice, like "Get my plan", or when it names the thing they get, like a seat, an audit or a guide.';
+        case 'strong_action_verb':
+            return `It opens with "${first}". A button should open with the verb of the action, like "Get", "Book" or "Start".`;
+        case 'low_friction':
+            return words ? `At ${words} words it reads like a sentence. Keep a button to a few words.` : 'The button is empty.';
+        case 'specificity':
+            return 'There is no number, name or timeframe in it, so it is easy to forget. Anchor it with one.';
+        case 'mechanism_named':
+            return 'It doesn\'t say how the result happens. Readers who have heard the promise before believe it more when you name the mechanism, with a "because" or a "by".';
+        case 'proof_welded':
+            return type === 'body_claim' ? 'There is nothing in it a skeptic could check. Put a real number or a named source right next to the claim.' : null;
+        case 'empty':
+            return 'The claim is empty.';
+        case 'too_long':
+            return 'That is too long to check as a single claim. For a whole block of copy, use diagnose_marketing_copy.';
+        default:
+            return null;
+    }
+}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@coppica/persuasion-mcp",
+  "version": "1.0.1",
+  "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",
+  "bin": {
+    "persuasion-mcp": "dist/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    },
+    "./http": {
+      "types": "./dist/http.d.ts",
+      "default": "./dist/http.js"
+    }
+  },
+  "files": [
+    "dist",
+    "data",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "export-data": "node --env-file=../persuasion-taxonomy/.env.local scripts/export-catalog.mjs",
+    "smoke": "node scripts/smoke.mjs",
+    "voice": "node scripts/voice-check.mjs",
+    "prepublishOnly": "npm run build && npm run smoke && npm run smoke -- --http && npm run voice"
+  },
+  "license": "MIT AND CC-BY-4.0",
+  "author": "Coppica LLC (https://coppica.com)",
+  "homepage": "https://taxonomy.coppica.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Otha-Labs/persuasion-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Otha-Labs/persuasion-mcp/issues"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "marketing",
+    "copywriting",
+    "persuasion",
+    "conversion",
+    "landing-page",
+    "headlines",
+    "ab-testing",
+    "claude",
+    "chatgpt"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@supabase/supabase-js": "^2.45.0",
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}