marketing-mindset-mcp 1.0.0 → 1.0.2

package/README.md

@@ -33,6 +33,8 @@ Client config (generic stdio server):
 | `read_section` | one section by fuzzy title match (`"numbers lie"`, `"competitors"`, `"hypotheses"`) |
 | `sample_size` | per-arm volume a two-proportion test needs before a verdict is readable |
 | `kill_rule` | expected conversions, the kill floor, and whether the test has enough volume to read yet |
+| `aeo_check` | agent-readiness / AEO audit: the 23 weighted checks that decide whether AI answers can find, read and quote a site; pass the numbers you pass to get a weighted score |
+| `jd` | a marketing-engineer job description about artifacts and numbers: what the role owns, what must exist by day 90, how it is measured, screening questions |
 
 `sample_size` and `kill_rule` implement the same two-proportion arithmetic as the free
 [test-size calculator](https://axelfreeman.github.io/marketing-mindset/tools/email-test-planner.html).
@@ -44,6 +46,32 @@ tools/call sample_size {"baseline_rate": 0.03, "min_relative_lift": 0.2}
 -> per_arm 13914   (i.e. ~13.9k sends per variant before any verdict)
 ```
 
+
+## Example: the AEO audit
+
+```
+tools/call aeo_check {}
+-> 23 checks, max score 55, grouped into crawlability, answer-ready content, machine-readable, someone else's page, proof and measurement
+
+tools/call aeo_check {"checked": [1,2,4,6,8,11,12,16,20,21,22]}
+-> score, band and the highest-weight gaps
+```
+
+The same checklist is a free page: [agent-readiness checklist](https://axelfreeman.github.io/marketing-mindset/tools/aeo-readiness-checklist.html). The JD tool has a web version too: [JD generator](https://axelfreeman.github.io/marketing-mindset/tools/marketing-engineer-jd-generator.html).
+
 ## License
 
 MIT.
+
+## Work with me
+
+This package is the method, packaged. The done-for-you version — offer page, query-intent source pages,
+schema and `llms.txt`, a free tool, deliverability setup, tests with a written kill rule, and the tracked
+event in your own analytics property — is built in fixed packages:
+[Sprint $900 one-time, Engine $1,900/month, Full build $2,900](https://axelfreeman.com/marketing-engineer.html).
+
+Live artifacts from the same engine, all openable:
+[proof page](https://axelfreeman.com/proof.html) ·
+[query-intent pages](https://axelfreeman.com/hire-marketing-engineer.html) ·
+[free test-size calculator](https://axelfreeman.github.io/marketing-mindset/tools/email-test-planner.html) ·
+[Telegram](https://t.me/AxelFreeman).

package/bin/server.js

@@ -9,7 +9,7 @@ const fs = require("fs");
 const path = require("path");
 
 const SKILL_PATH = path.join(__dirname, "..", "skill", "SKILL.md");
-const SERVER = { name: "marketing-mindset-mcp", version: "1.0.0" };
+const SERVER = { name: "marketing-mindset-mcp", version: "1.0.2" };
 const PROTOCOL = "2024-11-05";
 
 function skillText() {
@@ -63,16 +63,116 @@ function killRule(rate, n, lift) {
   const floor = Math.max(0, Math.floor(bound));
   const expected = rate * n;
   const target = rate * (1 + lift) * n;
-  let verdict = "keep running — not enough volume to read the result";
+  let verdict = "keep running - not enough volume to read the result";
   if (n < sampleSize(rate, lift, 0.8, 0.975)) {
-    verdict = "keep running — below the required volume for this effect size, a verdict now is noise";
+    verdict = "keep running - below the required volume for this effect size, a verdict now is noise";
   } else {
-    verdict = "read it — volume is sufficient; kill if conversions are at or under the floor";
+    verdict = "read it - volume is sufficient; kill if conversions are at or under the floor";
   }
   return { expected_conversions: Math.round(expected * 10) / 10, kill_floor: floor,
            target_conversions: Math.round(target * 10) / 10, verdict };
 }
 
+/* --- agent readiness / AEO checklist: 5 groups, 23 checks, 55 points ------------------------ */
+const AEO_GROUPS = [["Crawlability",[["robots.txt does not block GPTBot, ClaudeBot, PerplexityBot, Google-Extended, OAI-SearchBot",3],["Pages render without JavaScript, or have a server-side/no-JS fallback",2],["No login wall or consent interstitial in front of the content you want quoted",3],["The page returns 200 to a plain curl with no cookies",2],["One canonical URL per answer - no www/non-www or trailing-slash duplicates",2]]],["Answer-ready content",[["Every important page answers one question in the first 60 words",3],["Headings are questions a human would type, not internal project names",2],["Prices, limits and timeframes are stated as numbers, not 'flexible'",3],["Claims have a source or a live URL attached",2],["A definition page exists for the category you want to be cited in",3]]],["Machine-readable",[["schema.org markup on service/product pages (Service, Offer, Product, FAQPage)",3],["FAQPage or QAPage markup on question pages, answers 40-500 words",2],["XML sitemap submitted, and every new URL pinged via IndexNow",2],["llms.txt describes what the site answers and where the canonical pages are",2],["Organisation/Person entity links the page to a real, verifiable identity",2]]],["Someone else's page",[["You are present where the model already reads: package registries, repos, docs",3],["At least one open, mergeable pull request or discussion contribution",2],["Your content is mirrored somewhere you do not control",2],["A third-party page links to your canonical URL",3]]],["Proof and measurement",[["Every claim on the site can be opened by the reader in one click",3],["One tracked event for the outcome that matters, in your own analytics property",3],["A public changelog or artifact list with dates",2],["An archived snapshot of the key pages exists",1]]]];
+const AEO_MAX = AEO_GROUPS.reduce((a, g) => a + g[1].reduce((b, c) => b + c[1], 0), 0);
+
+function aeoFlat() {
+  const out = [];
+  AEO_GROUPS.forEach(([group, items]) => items.forEach(([text, weight]) => out.push({ group, check: text, weight })));
+  return out;
+}
+
+function aeoCheck(checked) {
+  const flat = aeoFlat();
+  const base = { check_count: flat.length, max_score: AEO_MAX,
+                 groups: AEO_GROUPS.map(([g, its]) => ({ group: g, checks: its.map(([t, w]) => ({ check: t, weight: w })) })),
+                 score_guide: "<30% invisible for structural reasons; 30-60% crawlable but not quotable; 60-80% quoted occasionally (third-party presence missing); >80% the rest is cadence" };
+  if (!Array.isArray(checked)) return Object.assign({}, base, { mode: "checklist" });
+  const idx = checked.map((v) => Number(v)).filter((n) => Number.isInteger(n) && n >= 1 && n <= flat.length);
+  const passed = new Set(idx);
+  const score = flat.reduce((a, c, i) => a + (passed.has(i + 1) ? c.weight : 0), 0);
+  const pct = Math.round((score / AEO_MAX) * 1000) / 10;
+  const missing = flat.map((c, i) => ({ n: i + 1, check: c.check, group: c.group, weight: c.weight }))
+    .filter((c) => !passed.has(c.n)).sort((a, b) => b.weight - a.weight).slice(0, 3);
+  return { mode: "score", passed: passed.size, of_checks: flat.length, score, max_score: AEO_MAX,
+           percent: pct,
+           band: pct < 30 ? "invisible for structural reasons" : pct < 60 ? "crawlable but not quotable"
+             : pct < 80 ? "quoted occasionally - third-party presence is the gap" : "the rest is cadence",
+           highest_weight_unchecked: missing,
+           note: "Weighted, not a checklist of equals. Two checks carry the most weight: one question answered in the first 60 words, and prices/limits stated as numbers." };
+}
+
+/* --- marketing engineer JD generator (same text as the npm CLI `jd` and the free web tool) --- */
+const JD_SURFACES = {
+  seo: "search and answer engines (pages written to be quoted, schema, llms.txt)",
+  out: "outbound and lifecycle email (list, sequence, deliverability, suppression)",
+  paid: "paid acquisition (structure, creative, spend gates)",
+  auto: "automation and tracking (routing, events, failure alerts)",
+  analytics: "measurement (one event that matters, sample-size floors, kill rules)",
+  ai: "agent skills and AI-assisted production (reusable operating files, not one-off prompts)",
+};
+const JD_OFFER = "https://axelfreeman.com/marketing-engineer.html";
+const JD_COST = "https://axelfreeman.com/marketing-engineer-cost.html";
+const JD_TOOL = "https://axelfreeman.github.io/marketing-mindset/tools/marketing-engineer-jd-generator.html";
+
+function jdText(o) {
+  const dflt = (v, d) => (v === undefined || v === null || v === "" || v === true) ? d : String(v);
+  const level = dflt(o.level, "senior");
+  const mode = dflt(o.mode, level === "contract" ? "contract" : "fulltime");
+  const sv = dflt(o.surfaces, null);
+  const keys = sv ? sv.split(",").map((s) => s.trim()).filter((s) => JD_SURFACES[s]) : Object.keys(JD_SURFACES);
+  const surf = keys.length ? keys : Object.keys(JD_SURFACES);
+  const company = dflt(o.company, "[company, product, what you sell in one line]");
+  const bottleneck = dflt(o.bottleneck, "[the bottleneck you are hiring against]");
+  const ninety = mode === "contract"
+    ? "A 6-week engagement with one written kill rule, then a decision"
+    : level === "lead"
+      ? "A documented system: which paths exist, what each one costs, what gets killed next quarter"
+      : "A path live in production with its event recording, or a written note saying why it was killed";
+  const L = [];
+  L.push("# Marketing Engineer (" + level + ", " + mode + ")", "");
+  L.push("## The company and the job");
+  L.push(company + ".", "");
+  L.push("We are hiring a marketing engineer because: " + bottleneck + ".", "");
+  L.push("You will not be handed a channel to run and a deck to fill in. You will be handed a broken or "
+       + "unmeasured path and be expected to make it work, show the number, and write the rule that decides "
+       + "whether it lives.", "");
+  L.push("## What the role owns");
+  surf.forEach((k, i) => L.push((i + 1) + ". " + JD_SURFACES[k]));
+  L.push("", "## What must exist by day 90");
+  L.push("1. One path live in production: entry point, sequence or flow, and the event that fires on a conversion.");
+  L.push("2. A written declaration of the sample size each running test needs before a result counts as a result.");
+  L.push("3. A kill rule per test, written before the test starts: at what volume and what result we stop.");
+  L.push("4. One dashboard we can open without asking you for an export.");
+  L.push("5. " + ninety + ".");
+  L.push("", "## How we will measure you");
+  L.push("- Cost per qualified conversation or per activated account, when the volume is above the declared floor.");
+  L.push("- Live, openable artifacts still running 30 days after you last touched them.");
+  L.push("- Whether a decision made last month can be re-checked today from the data, without you in the room.");
+  L.push("- We do not count posts published, prompts written, or hours logged.");
+  L.push("", "## Requirements");
+  L.push("- You have shipped something that is still running: a page, a sequence, a script, an integration. Links beat adjectives.");
+  L.push("- You can explain, in one paragraph, why a 4-of-100 result is not a win.");
+  L.push("- You work in the tooling yourself: HTML/CSS, a spreadsheet, analytics, basic scripting, or an agent that writes them for you.");
+  L.push("- You write plainly; internal names and jargon are not allowed in anything a customer reads.");
+  L.push("", "## Nice to have");
+  L.push("- Experience writing pages that answer engines quote (schema, FAQ markup, plain HTML).");
+  L.push("- A history of killing your own work in public, with the numbers attached.");
+  L.push("", "## Not this role");
+  L.push("- Meeting-led account management, community management, brand campaigns, reporting for its own sake.");
+  L.push("", "## Screening questions (ask these first)");
+  L.push("1. Send us one link to something you built that is still live.");
+  L.push("2. We ran 40 sends, got 4 replies, variant B looks better. What do you do next?");
+  L.push("3. How many sends does a two-variant email test need before the result means anything? "
+       + "(Expected: ~1,500-2,000 per arm at a 3% baseline, 80% power, 20% relative lift.)");
+  L.push("4. Name one thing you killed and what the number was.");
+  L.push("5. What will you build in the first two weeks here, and how will we see it?");
+  L.push("", "--", "Generated by marketing-mindset (npm). Method and pricing: " + JD_OFFER
+       + "  |  Packages: " + JD_COST + "  |  Web version of this tool: " + JD_TOOL);
+  return L.join("\n");
+}
+
 const TOOLS = [
   {
     name: "list_sections",
@@ -107,17 +207,38 @@ const TOOLS = [
         min_relative_lift: { type: "number", description: "Smallest relative lift worth detecting" }
       },
       required: ["baseline_rate", "n", "min_relative_lift"], additionalProperties: false }
+  },
+  {
+    name: "aeo_check",
+    description: "Agent-readiness / AEO audit: the 23 weighted checks that decide whether AI answers can find, read and quote a site. Call with no arguments for the checklist; pass the 1-based numbers of the checks the site passes (e.g. {\"checked\":[1,2,4,6,8,11,12]}) to get the weighted score, the band and the highest-weight gaps.",
+    inputSchema: { type: "object",
+      properties: { checked: { type: "array", items: { type: "integer" },
+                              description: "Optional: 1-based numbers of checks the site passes, out of 23" } },
+      additionalProperties: false }
+  },
+  {
+    name: "jd",
+    description: "Generates a marketing-engineer job description that is about artifacts and numbers instead of adjectives: what the role owns, what must exist by day 90, how it is measured, and the screening questions (including the sample-size question with the expected answer).",
+    inputSchema: { type: "object",
+      properties: {
+        level: { type: "string", description: "senior (default), lead, or contract" },
+        mode: { type: "string", description: "fulltime (default) or contract" },
+        surfaces: { type: "string", description: "Comma-separated subset of: seo, out, paid, auto, analytics, ai. Default: all." },
+        company: { type: "string", description: "One line about the company/product" },
+        bottleneck: { type: "string", description: "The bottleneck you are hiring against" }
+      },
+      additionalProperties: false }
   }
 ];
 
 function callTool(name, args) {
   args = args || {};
   if (name === "list_sections") {
-    return headingList().map((h) => `${"#".repeat(h.level)} ${h.title}`).join("\n");
+    return headingList().map((h) => "#".repeat(h.level) + " " + h.title).join("\n");
   }
   if (name === "read_section") {
     const s = readSection(args.section);
-    if (!s) return `No section matching "${args.section}". Call list_sections for the index.`;
+    if (!s) return 'No section matching "' + args.section + '". Call list_sections for the index.';
     return s.text;
   }
   if (name === "sample_size") {
@@ -140,6 +261,12 @@ function callTool(name, args) {
     out.volume_in_test = n;
     return JSON.stringify(out, null, 2);
   }
+  if (name === "aeo_check") {
+    return JSON.stringify(aeoCheck(args.checked), null, 2);
+  }
+  if (name === "jd") {
+    return jdText(args);
+  }
   throw new Error("Unknown tool: " + name);
 }
 
@@ -154,7 +281,7 @@ function handle(msg) {
   const { id, method, params } = msg;
   if (method === "initialize") {
     return reply(id, { protocolVersion: PROTOCOL, capabilities: { tools: {} }, serverInfo: SERVER,
-      instructions: "Marketing decision rules as tools. Start with list_sections, then read_section. Use sample_size and kill_rule before spending on a test." });
+      instructions: "Marketing decision rules as tools. Start with list_sections, then read_section. Use sample_size and kill_rule before spending on a test, aeo_check to audit whether AI answers can quote a site, and jd to write the role down." });
   }
   if (method === "notifications/initialized" || (method || "").startsWith("notifications/")) return;
   if (method === "ping") return reply(id, {});

package/package.json

@@ -1,16 +1,19 @@
 {
   "name": "marketing-mindset-mcp",
-  "version": "1.0.0",
-  "description": "MCP server for the open marketing-mindset skill: test-size math, kill rules and the section index as callable tools for any MCP client (Claude Code, Codex, Hermes, Cursor).",
+  "version": "1.0.2",
+  "description": "MCP server for the open marketing-mindset skill: test-size math, kill rules, AEO agent-readiness audit and a marketing-engineer JD generator as callable tools for any MCP client (Claude Code, Codex, Hermes, Cursor).",
   "keywords": [
+    "ab-testing",
+    "aeo",
+    "agent-skill",
+    "answer-engine-optimization",
+    "growth",
+    "job-description",
+    "marketing",
     "mcp",
-    "model-context-protocol",
     "mcp-server",
-    "marketing",
-    "agent-skill",
-    "sample-size",
-    "ab-testing",
-    "growth"
+    "model-context-protocol",
+    "sample-size"
   ],
   "license": "MIT",
   "author": "Axel Freeman",