@coppica/persuasion-mcp 1.0.1

package/dist/stats.js

@@ -0,0 +1,112 @@
+/** Plain A/B test statistics. No dependencies, no network. */
+/** Standard normal CDF (Abramowitz & Stegun 7.1.26 via erf, |error| < 1.5e-7). */
+export function normCdf(z) {
+    const x = Math.abs(z) / Math.SQRT2;
+    const t = 1 / (1 + 0.3275911 * x);
+    const y = 1 - (((((1.061405429 * t - 1.453152027) * t) + 1.421413741) * t - 0.284496736) * t + 0.254829592) * t * Math.exp(-x * x);
+    return z >= 0 ? 0.5 * (1 + y) : 0.5 * (1 - y);
+}
+/** Inverse standard normal CDF (Acklam's rational approximation). */
+export function normInv(p) {
+    if (p <= 0 || p >= 1)
+        throw new Error('normInv: p must be in (0,1)');
+    const a = [-3.969683028665376e1, 2.209460984245205e2, -2.759285104469687e2, 1.38357751867269e2, -3.066479806614716e1, 2.506628277459239];
+    const b = [-5.447609879822406e1, 1.615858368580409e2, -1.556989798598866e2, 6.680131188771972e1, -1.328068155288572e1];
+    const c = [-7.784894002430293e-3, -3.223964580411365e-1, -2.400758277161838, -2.549732539343734, 4.374664141464968, 2.938163982698783];
+    const d = [7.784695709041462e-3, 3.224671290700398e-1, 2.445134137142996, 3.754408661907416];
+    const lo = 0.02425;
+    if (p < lo) {
+        const q = Math.sqrt(-2 * Math.log(p));
+        return (((((c[0] * q + c[1]) * q + c[2]) * q + c[3]) * q + c[4]) * q + c[5]) / ((((d[0] * q + d[1]) * q + d[2]) * q + d[3]) * q + 1);
+    }
+    if (p > 1 - lo) {
+        const q = Math.sqrt(-2 * Math.log(1 - p));
+        return -(((((c[0] * q + c[1]) * q + c[2]) * q + c[3]) * q + c[4]) * q + c[5]) / ((((d[0] * q + d[1]) * q + d[2]) * q + d[3]) * q + 1);
+    }
+    const q = p - 0.5;
+    const r = q * q;
+    return ((((((a[0] * r + a[1]) * r + a[2]) * r + a[3]) * r + a[4]) * r + a[5]) * q) / (((((b[0] * r + b[1]) * r + b[2]) * r + b[3]) * r + b[4]) * r + 1);
+}
+/** Visitors needed per version to detect a relative lift (two-sided, two-proportion z-test). */
+export function sampleSizePerArm(baseline, relativeLift, alpha, power) {
+    const p1 = baseline;
+    const p2 = baseline * (1 + relativeLift);
+    const za = normInv(1 - alpha / 2);
+    const zb = normInv(power);
+    const pbar = (p1 + p2) / 2;
+    const n = (za * Math.sqrt(2 * pbar * (1 - pbar)) + zb * Math.sqrt(p1 * (1 - p1) + p2 * (1 - p2))) ** 2 / (p2 - p1) ** 2;
+    return Math.ceil(n);
+}
+/** Two-proportion z-test (pooled SE for the test, unpooled SE for the interval). */
+export function compare(cA, nA, cB, nB, alpha) {
+    const rateA = cA / nA;
+    const rateB = cB / nB;
+    const diff = rateB - rateA;
+    const pooled = (cA + cB) / (nA + nB);
+    const sePooled = Math.sqrt(pooled * (1 - pooled) * (1 / nA + 1 / nB));
+    const z = sePooled > 0 ? diff / sePooled : 0;
+    const p = 2 * (1 - normCdf(Math.abs(z)));
+    const se = Math.sqrt((rateA * (1 - rateA)) / nA + (rateB * (1 - rateB)) / nB);
+    const zc = normInv(1 - alpha / 2);
+    return {
+        rateA, rateB, diff,
+        relLift: rateA > 0 ? diff / rateA : NaN,
+        z, p,
+        ciLow: diff - zc * se,
+        ciHigh: diff + zc * se,
+        probBBetter: se > 0 ? normCdf(diff / se) : 0.5,
+    };
+}
+/** Regularized upper incomplete gamma Q(a, x) (Numerical Recipes gammq). */
+function gammq(a, x) {
+    if (x < 0 || a <= 0)
+        return NaN;
+    if (x === 0)
+        return 1;
+    const gln = lnGamma(a);
+    if (x < a + 1) {
+        let sum = 1 / a, del = sum, ap = a;
+        for (let n = 0; n < 200; n++) {
+            ap += 1;
+            del *= x / ap;
+            sum += del;
+            if (Math.abs(del) < Math.abs(sum) * 1e-12)
+                break;
+        }
+        return 1 - sum * Math.exp(-x + a * Math.log(x) - gln);
+    }
+    let b = x + 1 - a, c = 1 / 1e-300, d = 1 / b, h = d;
+    for (let i = 1; i < 200; i++) {
+        const an = -i * (i - a);
+        b += 2;
+        d = an * d + b;
+        if (Math.abs(d) < 1e-300)
+            d = 1e-300;
+        c = b + an / c;
+        if (Math.abs(c) < 1e-300)
+            c = 1e-300;
+        d = 1 / d;
+        const del = d * c;
+        h *= del;
+        if (Math.abs(del - 1) < 1e-12)
+            break;
+    }
+    return Math.exp(-x + a * Math.log(x) - gln) * h;
+}
+function lnGamma(x) {
+    const cof = [76.18009172947146, -86.50532032941677, 24.01409824083091, -1.231739572450155, 0.1208650973866179e-2, -0.5395239384953e-5];
+    let y = x, tmp = x + 5.5;
+    tmp -= (x + 0.5) * Math.log(tmp);
+    let ser = 1.000000000190015;
+    for (const c of cof)
+        ser += c / ++y;
+    return -tmp + Math.log((2.5066282746310005 * ser) / x);
+}
+/** Sample ratio mismatch: chi-square goodness of fit of observed visitors against the intended split. */
+export function srmPValue(observed, intendedShares) {
+    const total = observed.reduce((a, b) => a + b, 0);
+    const shareSum = intendedShares.reduce((a, b) => a + b, 0);
+    let chi = 0;
+    observed.forEach((o, i) => { const e = (total * intendedShares[i]) / shareSum; chi += (o - e) ** 2 / e; });
+    return gammq((observed.length - 1) / 2, chi / 2);
+}

package/dist/tools/catalog.d.ts

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

package/dist/tools/catalog.js

@@ -0,0 +1,84 @@
+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 { joinList, clipText, innerQuotes } from '../voice.js';
+export function registerCatalogTools(server) {
+    server.registerTool('find_persuasion_techniques', {
+        title: '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, ' +
+            'how common it is in a category if you name one, and a link. So reach for it when a draft relies on the obvious move and you want a less expected one, ' +
+            'or when someone asks for tactics, angles, hooks or ideas.',
+        inputSchema: {
+            query: z.string().min(2).max(300).describe('What you want the copy to do, in plain words, like "prove it works without testimonials".'),
+            question: roleSchema.optional().describe('Set this to see only the techniques that answer one reader question.'),
+            format: formatSchema.optional(),
+            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;
+        const hits = searchTechniques(query, { role, format: format ?? null, limit });
+        if (!hits.length) {
+            return text(`Nothing matched "${query}"${role ? ` among the techniques that answer ${roleLabel(role)}` : ''}. ` +
+                `Describe the effect you want in plainer words${role ? ', or drop the question filter' : ''}.`);
+        }
+        const out = [`# Techniques for "${query}"${role ? `, each one a way to answer ${roleLabel(role)}` : ''}`];
+        for (const t of hits)
+            out.push(techniqueLine(t, { category: cat, after: role ? undefined : `It answers ${roleLabel(t.role)}.` }));
+        out.push('');
+        out.push('For the full entry, with how it works, when it backfires and more examples, call get_persuasion_technique with the ID.');
+        return text(out.join('\n'));
+    });
+    server.registerTool('get_persuasion_technique', {
+        title: '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.',
+        inputSchema: {
+            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) {
+            const near = searchTechniques(id, { limit: 5 });
+            return errorText(`There's no technique called "${id}".${near.length ? ` The closest matches are ${joinList(near.map((n) => `${n.name} (${n.pt_id})`))}.` : ''} ` +
+                'You can search the catalog with find_persuasion_techniques.');
+        }
+        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('');
+        // 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);
+        out.push(prose(t.lede));
+        if (t.what_it_does)
+            out.push(`\n**What it does.** ${prose(t.what_it_does)}`);
+        if (t.why_it_works)
+            out.push(`\n**Why it works.** ${prose(t.why_it_works)}`);
+        if (t.lands_when)
+            out.push(`\n**When it lands.** ${prose(t.lands_when)}`);
+        if (t.dilutes_when)
+            out.push(`\n**When it backfires.** ${prose(t.dilutes_when)}`);
+        if (t.examples.length) {
+            out.push('\n**Real examples**');
+            for (const e of t.examples) {
+                out.push(`- From ${exampleSource(e)}: "${innerQuotes(prose(e.headline || e.excerpt))}"${e.why ? ` ${prose(e.why)}` : ''}`);
+            }
+        }
+        if (t.sisters.length)
+            out.push(`\nRelated techniques: ${joinList(t.sisters.map((s) => `${s.name} (${s.pt_id})`))}.`);
+        if (t.counters.length)
+            out.push(`The opposite approach: ${joinList(t.counters.map((s) => `${s.name} (${s.pt_id})`))}.`);
+        out.push(`\nCite it as ${t.name} (${t.pt_id}), The Persuasion Taxonomy, Coppica, ${t.url}`);
+        return text(out.join('\n'));
+    });
+}

package/dist/tools/craft.d.ts

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

package/dist/tools/craft.js

@@ -0,0 +1,129 @@
+import { z } from 'zod';
+import { awarenessSchema, roleSchema } from '../schemas.js';
+import { text } from '../format.js';
+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';
+/** 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;
+const RATING = { fail: 'fails', weak: 'is weak', passable: 'is passable', strong: 'is strong', excellent: 'is excellent' };
+const briefSchema = z.object({
+    brand: z.string().max(200).optional().describe('The brand or product name.'),
+    product: z.string().max(400).optional().describe("What you're selling."),
+    offer: z.string().max(400).optional().describe('The deal or the ask, like the price, a discount, a trial or a deadline.'),
+    audience: z.string().max(400).optional().describe('Who reads it: their role, their situation and what is theirs.'),
+    proof: z.string().max(400).optional().describe('Real proof you can point to, like customer counts, results or names.'),
+}).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',
+        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. ' +
+            'Then it tells you what each option is betting on and which two to test. Before you call it, list the reader questions each line answers and quote the exact words doing the work. ' +
+            'Use it whenever you write headlines, hooks or subject lines, whenever you have to choose between them, and whenever someone asks "which one is best?" ' +
+            "You won't get a score out of ten. Nobody can predict a winner from the words alone, and that includes this tool.",
+        inputSchema: {
+            slot: z.enum(SLOTS).describe(`Where the lines will appear: ${SLOTS.join(', ')}. Each spot has its own job, and the check tells you what it is.`),
+            lines: z.array(z.object({
+                text: z.string().min(2).max(500).describe('The line, exactly as written.'),
+                answers: z.array(z.object({
+                    question: roleSchema,
+                    words: z.string().min(1).max(200).describe('The exact words in the line that answer it.'),
+                })).max(9).describe('The reader questions this line answers, each with the exact words that do it. Leave it empty if the line answers none.'),
+            })).min(1).max(20),
+            brief: briefSchema.optional(),
+            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'));
+        const checks = lines.map((l) => checkHook({
+            text: l.text, slot, brief, follows, awareness: awareness_level,
+            answers: l.answers.map((a) => ({ question: a.question, words: a.words })),
+        }));
+        const out = [];
+        out.push(`# ${lines.length > 1 ? `${lines.length} ${info.label}s` : `One ${info.label}`}, checked`);
+        out.push(`The job of ${article(info.label)} is to ${info.job}. ${endSentence(`To do that, it has to answer ${questionsNeeded(checks[0].needs)}`)}` +
+            `${info.visibleNote ? ` Keep in mind that ${info.visibleNote}.` : ''}`);
+        if (lines.length > 1) {
+            out.push('');
+            out.push('## Which to use');
+            out.push(compareHooks(checks, names));
+        }
+        checks.forEach((c, i) => {
+            out.push('');
+            out.push(`## ${lines.length > 1 ? `${names[i]}. ` : ''}"${c.text}" ${VERDICT_LABEL[c.verdict]}`);
+            const parts = [describeCheck(c)];
+            if (c.visible && c.visible !== c.text && !c.warnings.some((w) => w.includes(c.visible)))
+                parts.push(`What readers actually see is "${c.visible}".`);
+            if (c.unverified.length) {
+                parts.push(`${c.unverified.length === 1 ? "One label didn't" : "Some labels didn't"} count, because the quoted words aren't in the line: ` +
+                    `${joinList(c.unverified.map((a) => `"${a.words}" for ${a.question}`))}.`);
+            }
+            out.push(parts.join(' '));
+            out.push(c.fix.startsWith('Nothing') ? c.fix : `Here's the fix. ${c.fix}`);
+        });
+        out.push('');
+        if (checks.some((c) => c.evidence.length))
+            out.push(EVIDENCE_SOURCE);
+        out.push('Nobody can pick the winner from the words alone, and that includes this check. To find out, test two lines that make different bets, and size the test with plan_ab_test.');
+        return text(out.join('\n'));
+    });
+    server.registerTool('check_marketing_claims', {
+        title: '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. ' +
+            'For headlines, check_headlines does the full job.',
+        inputSchema: {
+            claims: z.array(z.object({
+                text: z.string().min(2).max(600).describe('The claim or the button text, exactly as written.'),
+                type: z.enum(['headline', 'cta', 'body_claim']).describe('Use headline, cta for a button or call to action, or body_claim for a claim inside the copy.'),
+                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.
+        const others = claims.filter((c) => c.type !== 'headline');
+        const scored = scoreClaims(others.map((c) => ({ text: c.text, type: c.type, context: c.context })));
+        let k = 0;
+        for (const c of claims) {
+            out.push('');
+            if (c.type === 'headline') {
+                const h = checkHook({ text: c.text, slot: 'landing_page_headline', answers: [] });
+                const issues = [...h.hardFails, ...h.warnings, ...h.evidenceAgainst];
+                out.push(`**"${c.text}"** (a headline). ${issues.length ? issues.join(' ') : 'The claim itself has no problems.'} ` +
+                    'To find out whether it does its job, and whether a competitor could send it, run check_headlines with the brief.');
+                continue;
+            }
+            const r = scored[k++];
+            const type = c.type === 'cta' ? 'cta' : 'body_claim';
+            const notes = [];
+            const stock = r.gates.some((g) => g.name === 'generic_button_text' && g.status === 'fail');
+            if (SUPERLATIVE.test(c.text) && !BACKED.test(c.text)) {
+                notes.push('It leans on an unproven superlative. Claims like "#1", "the best" and "leading" read as puffery unless the proof is in the same line, ' +
+                    'meaning who ranked it and by what measure, so name the source or swap it for a specific fact a reader could check.');
+            }
+            // A stock button gets one sentence about naming what the reader gets, not two.
+            for (const g of r.gates.filter((g) => g.status !== 'pass' && !(stock && g.name === 'first_person_or_outcome')).slice(0, 3)) {
+                const s = g.name === 'anti_smell' ? smellSentences(detectAISmell(c.text).violations).join(' ') : claimGateSentence(g.name, c.text, type);
+                if (s)
+                    notes.push(s);
+            }
+            const label = r.scoreLabel;
+            const lead = `**"${r.text}"** (${type === 'cta' ? 'a button' : 'a claim in the body'}) ${RATING[label] ?? label}.`;
+            const bridge = notes.length && (label === 'strong' || label === 'excellent') ? (notes.length === 1 ? ' One thing would make it stronger.' : ' A few things would make it stronger.') : '';
+            out.push(`${lead}${bridge} ${notes.length ? notes.join(' ') : 'Nothing in it needs fixing.'}`);
+        }
+        out.push('');
+        out.push("A claim persuades when it's specific, it's true and the proof sits right next to it. For ways to prove a claim, search find_persuasion_techniques with the question set to PROVE.");
+        return text(out.join('\n'));
+    });
+}

package/dist/tools/diagnose.d.ts

@@ -0,0 +1,5 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type Format } from '../roles.js';
+import { type Slot } from '../hookcheck/index.js';
+export declare const OPENING_SLOT: Record<Format, Slot>;
+export declare function registerDiagnoseTool(server: McpServer): void;

package/dist/tools/diagnose.js

@@ -0,0 +1,269 @@
+import { z } from 'zod';
+import { ROLE_NAMES, ROLES, GOAL_REQUIREMENTS, GOAL_NOUN, GOAL_CLAUSE, FORMAT_LABEL, COHERENCE_CHECKS, expectedRoles, roleLabel } from '../roles.js';
+import { pickMoves, resolveCategory } from '../data.js';
+import { goalSchema, formatSchema, awarenessSchema, categorySchema, roleSchema, modeSchema } from '../schemas.js';
+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';
+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',
+};
+/** Long-form pages: score the prose, not the scaffolding. Headings, buttons, placeholders and
+ *  short label lines otherwise count as sentences and wreck the rhythm checks. */
+function proseOnly(copy, format) {
+    if (format !== 'landing_page' && format !== 'sales_letter')
+        return { prose: copy, skipped: 0 };
+    let skipped = 0;
+    const kept = copy.split('\n').filter((raw) => {
+        const l = raw.trim();
+        if (!l)
+            return true;
+        const words = l.replace(/[*_#>\-\[\]()]/g, ' ').trim().split(/\s+/).filter(Boolean).length;
+        const scaffold = /^#{1,6}\s/.test(l) || /^-{3,}$/.test(l) || /^\[.*\]$/.test(l) || /^\*\*\[.*\]\*\*$/.test(l) ||
+            (words <= 6 && !/[.!]$/.test(l.replace(/\*+$/, '')));
+        if (scaffold)
+            skipped++;
+        return !scaffold;
+    }).map((l) => l.replace(/^\s*[-*>]\s+/, '').replace(/\*\*/g, ''));
+    const prose = kept.join('\n');
+    return prose.trim().split(/\s+/).length >= 60 ? { prose, skipped } : { prose: copy, skipped: 0 };
+}
+function flowContext(format, words) {
+    switch (format) {
+        case 'ad':
+        case 'social_post': return 'ad';
+        case 'email': return 'email';
+        case 'email_subject': return 'subject';
+        case 'headline': return 'header';
+        case 'sales_letter': return 'long_form';
+        default: return words > 1500 ? 'long_form' : 'body';
+    }
+}
+const normText = (s) => s.toLowerCase().replace(/[‘’]/g, "'").replace(/[“”]/g, '"').replace(/\s+/g, ' ').trim();
+const STATUS_RANK = { missing: 0, partial: 1, clear: 2 };
+export function registerDiagnoseTool(server) {
+    server.registerTool('diagnose_marketing_copy', {
+        title: '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. ' +
+            'It also checks the order, whether the answers agree with each other, and the craft, pointing to the exact words that read as machine-written, like em dashes, ' +
+            '"it\'s not X, it\'s Y" lines and sentences that all run the same length. Then it checks the opening line and suggests techniques from the catalog to fill the gap. ' +
+            "Use it before you show anyone a draft you wrote, and whenever someone asks \"is this good?\", \"roast this\", \"what's wrong with this copy?\" or \"how do I make it better?\"",
+        inputSchema: {
+            copy: z.string().min(10).max(30000).describe('The full copy, exactly as written.'),
+            goal: goalSchema,
+            format: formatSchema,
+            moves: z.array(z.object({
+                excerpt: z.string().min(2).max(400).describe('An exact quote from the copy, whether a sentence, a line or a short passage.'),
+                question: roleSchema,
+                clarity: z.enum(['clear', 'partial']).default('clear').describe('Use clear when the line answers the question well, and partial when it only gestures at it.'),
+            })).min(1).max(80).describe('Your line-by-line labels. Quote each persuasive line exactly and name the one reader question it mainly answers. Skip lines that are pure filler.'),
+            awareness_level: awarenessSchema.optional(),
+            category: categorySchema.optional(),
+            headline: z.string().max(300).optional().describe("The headline or opening line, if it isn't the first line of the copy."),
+            persuasion_mode: modeSchema,
+            brief: z.object({
+                brand: z.string().max(200).optional(),
+                product: z.string().max(400).optional(),
+                offer: z.string().max(400).optional(),
+                audience: z.string().max(400).optional(),
+                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);
+        const normCopy = normText(copy);
+        const goalNoun = GOAL_NOUN[goal];
+        // where each labeled move sits in the copy (falls back to the order given)
+        let unmatched = 0;
+        const placed = moves.map((m, i) => {
+            const ex = normText(m.excerpt);
+            let pos = normCopy.indexOf(ex);
+            if (pos < 0 && ex.length > 40)
+                pos = normCopy.indexOf(ex.slice(0, 40));
+            if (pos < 0)
+                unmatched++;
+            return { ...m, question: m.question, pos: pos < 0 ? Number.MAX_SAFE_INTEGER - (moves.length - i) : pos };
+        });
+        const ordered = unmatched > moves.length / 2 ? placed : [...placed].sort((a, b) => a.pos - b.pos);
+        const status = new Map();
+        const count = new Map();
+        for (const r of ROLE_NAMES) {
+            status.set(r, 'missing');
+            count.set(r, 0);
+        }
+        for (const m of placed) {
+            count.set(m.question, (count.get(m.question) ?? 0) + 1);
+            const s = m.clarity === 'clear' ? 'clear' : 'partial';
+            if (STATUS_RANK[s] > STATUS_RANK[status.get(m.question)])
+                status.set(m.question, s);
+        }
+        const reqs = GOAL_REQUIREMENTS[goal];
+        const reqStatus = reqs.map((req) => req.reduce((best, r) => (STATUS_RANK[status.get(r)] > STATUS_RANK[best] ? status.get(r) : best), 'missing'));
+        const clearN = reqStatus.filter((s) => s === 'clear').length;
+        const partialN = reqStatus.filter((s) => s === 'partial').length;
+        const out = [];
+        out.push(`# Diagnosis: ${FORMAT_LABEL[format]} that ${GOAL_CLAUSE[goal]}`);
+        out.push(`It clearly answers ${clearN} of the ${reqs.length} questions ${goalNoun} needs${partialN ? `, and ${partialN} more only weakly` : ''}. ` +
+            "That tells you what the copy covers. It can't tell you how the copy will convert, and only a test can.");
+        if (unmatched) {
+            out.push(`${unmatched} of the ${plural(moves.length, 'line')} you labeled ${unmatched === 1 ? "doesn't" : "don't"} appear word for word in the copy` +
+                `${unmatched > moves.length / 2 ? ', so the order checks follow the order you gave them' : ''}. Quote the copy exactly and the read gets sharper.`);
+        }
+        out.push('');
+        out.push('## The nine questions');
+        for (const r of ROLE_NAMES) {
+            const s = status.get(r);
+            const n = count.get(r);
+            const lines = n ? `, in ${plural(n, 'line')}` : '';
+            let label;
+            if (expected.has(r))
+                label = { clear: `Answered clearly${lines}`, partial: `Answered, but only weakly${lines}`, missing: 'Not answered' }[s];
+            else
+                label = s === 'missing' ? `Not needed for ${goalNoun}` : `${s === 'clear' ? 'Answered clearly' : 'Answered weakly'}${lines}, though ${goalNoun} can do without it`;
+            out.push(`${ROLES[r].num}. ${ROLES[r].question} (${r}) ${label}.`);
+        }
+        // biggest gap: first unmet requirement in canonical order; else first partial; else upgrade
+        const idxMissing = reqStatus.findIndex((s) => s === 'missing');
+        const idxPartial = reqStatus.findIndex((s) => s === 'partial');
+        let gapRole;
+        let mode;
+        if (idxMissing >= 0) {
+            gapRole = reqs[idxMissing][0];
+            mode = 'fix';
+        }
+        else if (idxPartial >= 0) {
+            gapRole = reqs[idxPartial][0];
+            mode = 'strengthen';
+        }
+        else {
+            gapRole = [...expected].sort((a, b) => (count.get(a) - count.get(b)) || ROLES[a].num - ROLES[b].num)[0];
+            mode = 'upgrade';
+        }
+        const gi = ROLES[gapRole];
+        out.push('');
+        if (mode === 'upgrade') {
+            out.push('## Every question it needs is answered');
+            out.push(`The thinnest answer is ${roleLabel(gapRole)}. Deepen it with a less expected move and the copy stops reading like the category default. Here are three ways to do it.`);
+        }
+        else {
+            const alt = reqs[mode === 'fix' ? idxMissing : idxPartial].slice(1);
+            out.push(`## ${mode === 'fix' ? 'The biggest gap' : 'The weakest answer'}: ${roleLabel(gapRole)}`);
+            out.push(`${mode === 'strengthen' ? "It's answered, but only weakly. " : ''}Leave it unanswered and this is what happens: "${gi.ifMissing}" Right now, ${gi.gap}.` +
+                `${alt.length ? ` Answering ${joinList(alt.map((r) => `"${ROLES[r].question}"`), 'or')} would also do.` : ''} Here are three ways to answer it.`);
+        }
+        for (const p of pickMoves(gapRole, { n: 3, format, category: cat, seed: copy.slice(0, 500), context: copy.slice(0, 4000), mode: persuasion_mode })) {
+            out.push(techniqueLine(p.t, { category: cat, kind: p.kind === 'established' ? 'established' : 'less expected' }));
+        }
+        // order
+        const orderNotes = [];
+        const first = ordered[0];
+        const lateAwareness = ['product_aware', 'most_aware'];
+        if (first && !['DISRUPT', 'IDENTIFY'].includes(first.question) && !(awareness_level && lateAwareness.includes(awareness_level))) {
+            orderNotes.push(`It opens by answering "${ROLES[first.question].question}" before it has earned attention or shown readers it's for them. ` +
+                `Unless they already know the product, open with "${ROLES.DISRUPT.question}" or "${ROLES.IDENTIFY.question}"`);
+        }
+        if (goal === 'purchase' || goal === 'signup') {
+            const firstCompel = ordered.findIndex((m) => m.question === 'COMPEL');
+            const firstProve = ordered.findIndex((m) => m.question === 'PROVE');
+            if (firstCompel >= 0 && (firstProve < 0 || firstProve > firstCompel))
+                orderNotes.push('It asks for action before anything has earned belief. Move the proof ahead of the first ask.');
+        }
+        if (goal === 'purchase') {
+            const lastCompel = ordered.map((m) => m.question).lastIndexOf('COMPEL');
+            const resolves = ordered.map((m, i) => (m.question === 'RESOLVE' ? i : -1)).filter((i) => i >= 0);
+            if (lastCompel >= 0 && resolves.length && resolves.every((i) => i > lastCompel)) {
+                orderNotes.push('It handles the objections after the final ask, so readers reach the ask with their doubts still standing, and that is where they leave. Answer the objections before you close.');
+            }
+        }
+        out.push('');
+        out.push('## The order');
+        out.push(orderNotes.length ? orderNotes.join(' ') : 'The order works for this goal.');
+        // coherence
+        const present = (r) => status.get(r) !== 'missing';
+        const flags = [];
+        if (present('ELEVATE') && !present('PROVE'))
+            flags.push("It promises a better life after, but there's no proof, and readers discount any promise they have no reason to believe.");
+        if (present('COMPEL') && !present('AGITATE') && !present('ELEVATE'))
+            flags.push("It pushes for action now without showing what's at stake, and urgency without stakes reads as pressure.");
+        if (present('DISRUPT') && goal !== 'click' && !present('PROVE') && expected.has('PROVE'))
+            flags.push("The opening makes a bold move that nothing later backs up, and a hook the body can't support reads as bait.");
+        const checks = COHERENCE_CHECKS.filter((c) => present(c.roles[0]) && present(c.roles[1])).slice(0, 4);
+        out.push('');
+        out.push('## Do the answers agree?');
+        if (flags.length)
+            out.push(flags.join(' '));
+        if (checks.length) {
+            out.push(`${flags.length ? 'Beyond that, ask' : 'Nothing contradicts outright, but ask'} yourself these questions before you finish.`);
+            for (const c of checks)
+                out.push(`- ${c.check}`);
+        }
+        if (!flags.length && !checks.length)
+            out.push('Too few questions are answered yet to check them against each other.');
+        // craft + AI tells
+        const words = copy.trim().split(/\s+/).length;
+        const { prose, skipped } = proseOnly(copy, format);
+        const flow = scoreFlow(prose, { context: flowContext(format, words) });
+        out.push('');
+        out.push(`## How it reads: ${flow.score.toFixed(1)} out of 10, ${flow.scoreLabel}`);
+        if (skipped)
+            out.push(`This scores the prose only, so it skipped ${plural(skipped, 'heading, button, placeholder or label line', 'headings, buttons, placeholders and label lines')}.`);
+        const spans = (pattern) => flow.violations.filter((v) => v.pattern === pattern && v.span && v.span.length <= 160).map((v) => v.span);
+        const failing = [...flow.gates.filter((g) => g.status === 'fail'), ...flow.gates.filter((g) => g.status === 'warn')].slice(0, 6);
+        for (const g of failing) {
+            let s = flowGateSentence(g);
+            if (!s)
+                continue;
+            if (g.name === 'negative_parallelism_cap') {
+                const sp = spans('negative_parallelism').slice(0, 2);
+                if (sp.length)
+                    s += ` Look at ${joinList(sp.map((x) => `"${x}"`))}.`;
+            }
+            if (g.name === 'closing_recap') {
+                const [sp] = spans('closing_recap');
+                if (sp)
+                    s += ` It starts with "${sp}".`;
+            }
+            out.push(`- ${s}`);
+        }
+        if (!failing.length)
+            out.push('The craft is clean, with no machine-written tells.');
+        // headline
+        const hl = (headline ?? copy.split('\n').map((l) => l.trim().replace(/^#+\s*/, '').replace(/\*\*/g, '')).find((l) => l.length > 0) ?? '').slice(0, 300);
+        if (hl) {
+            const nh = normText(hl);
+            const answers = placed.flatMap((m) => {
+                const ne = normText(m.excerpt);
+                if (nh.includes(ne))
+                    return [{ question: m.question, words: m.excerpt }];
+                if (ne.includes(nh))
+                    return [{ question: m.question, words: hl }];
+                return [];
+            });
+            const hc = checkHook({ text: hl, slot: OPENING_SLOT[format], answers, brief, context: copy.replace(hl, ''), awareness: awareness_level });
+            out.push('');
+            out.push(`## The opening line ${VERDICT_LABEL[hc.verdict]}`);
+            out.push(`"${hl}"`);
+            out.push(describeCheck(hc, { evidence: false }));
+            if (hc.evidence.length)
+                out.push(`${hc.evidence.join(' ')} Those figures come from thousands of real headline tests on news stories, so treat them as a nudge.`);
+            out.push(hc.fix.startsWith('Nothing') ? hc.fix : `Here's the fix. ${hc.fix}`);
+        }
+        const steps = [`Start by ${mode === 'upgrade' ? 'deepening' : 'answering'} "${gi.question}" with one of the moves above.`];
+        if (orderNotes.length)
+            steps.push('Then fix the order.');
+        if (failing.length)
+            steps.push(`${orderNotes.length ? 'After that, fix' : 'Then fix'} the first problem in how it reads.`);
+        steps.push("One pass is usually enough, so only check again if you changed the structure, and don't chase the craft score.");
+        out.push('');
+        out.push('## What to do next');
+        out.push(steps.join(' '));
+        out.push('When you want to know what actually converts, test two different answers to the same question, and size the test with plan_ab_test.');
+        return text(out.join('\n'));
+    });
+}

package/dist/tools/plan.d.ts

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