research-lens-mcp 2.0.0 → 2.3.0

package/README.md

@@ -45,6 +45,18 @@ Research Lens gives the assistant direct, structured access to your repository.
 | "Did the redesign work?" | `compare_rounds` | Sentiment, completion and SUS, round over round |
 | "Draft a finding on onboarding" | `draft_findings` | Evidence with citations, plus what the data does not support |
 
+Teams shipping on a release schedule, and anyone whose decisions have to survive an audit, get five more:
+
+| Ask | Tool | You get |
+|---|---|---|
+| "What's still open before we ship?" | `release_readiness` | Issues by the severity you tagged, participants affected, quotes behind each |
+| "Did it improve since last release?" | `track_metric` | Completion and SUS per study in date order, never averaged across studies |
+| "Has anyone studied this already?" | `prior_research` | Which past studies touched a topic, when, with how many participants |
+| "Why did we make that change?" | `evidence_trail` | Every verbatim quote behind one issue, with participant, study, release and date |
+| "Whose experience are we guessing about?" | `coverage_gaps` | Segments, regions and themes resting on too few people |
+
+`release_readiness` ends with what it is *not*: not a ship decision, not a severity judgment, not frequency in the wild. `coverage_gaps` ends by naming the gap no tool can show you, the people your recruitment never reached.
+
 ## The constraint
 
 **The server retrieves and counts. It does not interpret.**
@@ -61,6 +73,35 @@ That line is enforced, not aspirational, and it shows up in four places:
 
 The tools never say what a finding *means*. That judgment stays with the researcher. This is the line between AI that accelerates research and AI that quietly replaces thinking with plausible text.
 
+## Consent, enforced at the point of query
+
+Research platforms manage consent at the storage layer: who can log into the tool. Research
+Lens enforces it at the **query** layer, where an AI agent actually reads. Each participant
+carries what they agreed to, and the server obeys it.
+
+| Consent | What happens |
+|---|---|
+| `full` | Quotes reproduced normally. The default, so existing studies are unaffected. |
+| `internal` | Quotes shown to the research team, withheld when the output is external. |
+| `counts` | Counted in every pattern, never quoted. They agreed to be studied, not published. |
+| `withdrawn` | Removed from every count, quote and **denominator**. |
+
+Set `RESEARCH_LENS_AUDIENCE=external` when the answer will leave the research team.
+
+A withheld quote is always labelled:
+
+```
+MIXED (1)
+  [P07 | R1 | 02:55] [quote withheld: consented to research-team use only, and this output is external]
+```
+
+It is never silently dropped. "Nobody said this" and "someone said this and did not consent
+to it leaving" must never look the same, because one is a finding and the other is a
+compliance breach wearing a finding's clothes.
+
+`consent_status` reports who agreed to what, who withdrew, and what is being withheld right
+now. Consent is read from the data and never inferred.
+
 ## Install
 
 **Claude Desktop.** Open your config:
@@ -98,7 +139,14 @@ Node 18 or newer. Nothing to clone, nothing to build.
 
 ## Your data
 
-`RESEARCH_LENS_DATA` points at a folder. One `.json` file per study, added or edited any time — the server re-reads on every question, so no restart.
+`RESEARCH_LENS_DATA` points at a folder of `.json` files, added or edited any time — the server
+re-reads on every question, so no restart.
+
+**Split a study across as many files as you like.** Files that declare the same `study.name` are
+merged into one study, so one file per interview works exactly as well as one file per study. A
+study split across files is still one study and its participants belong in one denominator.
+Repeated participant-and-round pairs are skipped rather than double counted, and `list_studies`
+reports which files were merged and anything it dropped.
 
 ```json
 {
@@ -131,7 +179,7 @@ Only `id`, `round`, `segment` and the excerpt fields are required. Everything el
 **From a spreadsheet.** Fill in [`template.csv`](template.csv), one row per quote, then:
 
 ```bash
-npx research-lens-mcp-import my-study.csv "Study name"
+npx -p research-lens-mcp research-lens-import my-study.csv "Study name"
 ```
 
 It validates every row, names the row and the reason if something is wrong, and writes nothing until the file is clean.

package/build/index.js

@@ -29,6 +29,7 @@ import { readFileSync, readdirSync, existsSync, statSync } from "node:fs";
 import { basename, dirname, extname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 const __dirname = dirname(fileURLToPath(import.meta.url));
+const SEVERITY_ORDER = ["blocker", "major", "minor"];
 /** Where studies live. A folder of .json files, or a single .json file. */
 const DATA_PATH = process.env.RESEARCH_LENS_DATA?.trim();
 const SAMPLE_DIR = join(__dirname, "..", "data");
@@ -58,19 +59,20 @@ function studyFiles() {
  * reads better than whatever the file happens to be called; the filename is the
  * fallback. Collisions get a numeric suffix so two studies never share a handle.
  */
-function keyFor(parsed, file, taken) {
+function keyFor(parsed, file) {
     const slug = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 40);
-    const base = slug(String(parsed.study?.name ?? "")) || slug(basename(file, ".json")) || "study";
-    if (!taken.some((t) => t.key === base))
-        return base;
-    let n = 2;
-    while (taken.some((t) => t.key === `${base}-${n}`))
-        n++;
-    return `${base}-${n}`;
+    return slug(String(parsed.study?.name ?? "")) || slug(basename(file, ".json")) || "study";
 }
-/** Read every study fresh on each call, so edits take effect with no restart. */
+/**
+ * Read every study fresh on each call, so edits take effect with no restart.
+ *
+ * Files that declare the same study name are MERGED into one study. A study
+ * split across one file per interview is still one study, and its participants
+ * belong in one denominator. Splitting the file should never silently split
+ * the evidence.
+ */
 function loadAll() {
-    const out = [];
+    const byKey = new Map();
     for (const file of studyFiles()) {
         let parsed;
         try {
@@ -82,9 +84,29 @@ function loadAll() {
         if (!Array.isArray(parsed?.sessions)) {
             throw new DataError(`"${basename(file)}" has no "sessions" array.`);
         }
-        out.push({ ...parsed, key: keyFor(parsed, file, out), file });
+        const key = keyFor(parsed, file);
+        const existing = byKey.get(key);
+        const stamp = (ss) => ss.map((x) => ({ ...x, round: x.round ?? 1, _file: basename(file) }));
+        if (!existing) {
+            byKey.set(key, { ...parsed, sessions: stamp(parsed.sessions), key, files: [basename(file)], duplicates: [] });
+            continue;
+        }
+        // Merge, but never count the same participant-round twice.
+        const seen = new Set(existing.sessions.map((s) => `${s.id}|${s.round}`));
+        for (const sess of parsed.sessions) {
+            const sig = `${sess.id}|${sess.round}`;
+            if (seen.has(sig)) {
+                existing.duplicates.push(`${sess.id} round ${sess.round} (${basename(file)})`);
+                continue;
+            }
+            seen.add(sig);
+            existing.sessions.push({ ...sess, round: sess.round ?? 1, _file: basename(file) });
+        }
+        existing.files.push(basename(file));
+        // Keep whichever study block carries the most context.
+        existing.study = { ...parsed.study, ...existing.study };
     }
-    return out;
+    return [...byKey.values()];
 }
 /**
  * Pick the studies a call applies to. With no name given, every study is used,
@@ -105,19 +127,86 @@ function pick(all, name) {
 }
 /** Flatten every excerpt with its session and study context attached. */
 function allExcerpts(studies) {
-    return studies.flatMap((st) => st.sessions.flatMap((s) => s.excerpts.map((e) => ({
+    return studies.flatMap((st) => active(st.sessions).flatMap((s) => s.excerpts.map((e) => ({
         ...e,
         participant: s.id,
         round: s.round,
         segment: s.segment,
         task: s.task,
         study: st.key,
+        consent: consentOf(s),
+        // An explicit source always shows. The filename only helps when a study
+        // was assembled from several files, so it stays hidden otherwise.
+        source: s.source ?? (st.files.length > 1 ? s._file ?? "" : ""),
     }))));
 }
-const sessionsOf = (studies) => studies.flatMap((s) => s.sessions);
+const sessionsOf = (studies) => studies.flatMap((s) => active(s.sessions));
+const norm = (s) => String(s ?? "").trim().toLowerCase();
+/**
+ * Who is asking. An MCP client is a pipe to wherever the answer ends up, so the
+ * operator declares the audience once, the way an API caller declares its scope.
+ * Defaults to the research team, the most permissive setting, because an
+ * existing study with no consent field should keep working unchanged.
+ */
+const AUDIENCE = norm(process.env.RESEARCH_LENS_AUDIENCE) === "external" ? "external" : "team";
+const consentOf = (s) => s.consent ?? "full";
+/** Withdrawn participants are removed from everything, including denominators. */
+const active = (xs) => xs.filter((x) => consentOf(x) !== "withdrawn");
+/** May this participant's words be reproduced, for this audience? */
+function mayQuote(consent) {
+    if (consent === "withdrawn" || consent === "counts")
+        return false;
+    if (consent === "internal")
+        return AUDIENCE === "team";
+    return true;
+}
+/**
+ * Renders a quote, or says plainly that it is being withheld and why. Never
+ * silently omits: a reader must be able to tell the difference between
+ * "nobody said this" and "someone said this and did not consent to it leaving".
+ */
+function quoteOrWithheld(h) {
+    if (mayQuote(h.consent))
+        return `"${h.quote}"`;
+    return h.consent === "counts"
+        ? `[quote withheld: participant consented to be counted, not quoted]`
+        : `[quote withheld: consented to research-team use only, and this output is external]`;
+}
+/**
+ * Themes are matched case-insensitively. An assistant will naturally write
+ * "Trust" for a theme filed as "trust", and returning "no quotes" for a
+ * capital letter would read as an absence of evidence, which is the most
+ * dangerous wrong answer this server could give.
+ */
+const themeMatches = (rowTheme, wanted) => norm(rowTheme) === norm(wanted);
+/** When a theme finds nothing, say what does exist rather than just "none". */
+function themeSuggestion(rows, wanted) {
+    const all = [...new Set(rows.map((r) => r.theme))];
+    if (!all.length)
+        return "";
+    const q = norm(wanted);
+    const near = all.filter((t) => norm(t).includes(q) || q.includes(norm(t)));
+    return near.length
+        ? ` Did you mean: ${near.join(", ")}?`
+        : ` Themes in scope: ${all.join(", ")}.`;
+}
+/** Optional segment filter, case-insensitive, shared by the retrieval tools. */
+function applySegment(rows, segment) {
+    if (!segment)
+        return { rows, label: "" };
+    const q = norm(segment);
+    const hit = rows.filter((r) => norm(r.segment) === q);
+    if (hit.length)
+        return { rows: hit, label: `, segment "${segment}"` };
+    const loose = rows.filter((r) => norm(r.segment).includes(q));
+    return { rows: loose, label: `, segment "${segment}"` };
+}
 /** Prefix a citation with the study only when more than one is in scope. */
-const cite = (h, multi) => `${multi ? h.study + " | " : ""}${h.participant} | R${h.round} | ${h.t}`;
-const server = new Server({ name: "research-lens", version: "2.0.0" }, { capabilities: { tools: {} } });
+const cite = (h, multi, showRound = true) => `${multi ? h.study + " | " : ""}${h.participant}` +
+    (showRound && h.round != null ? ` | R${h.round}` : "") +
+    ` | ${h.t}` +
+    (h.source ? ` | ${h.source}` : "");
+const server = new Server({ name: "research-lens", version: "2.3.0" }, { capabilities: { tools: {} } });
 const STUDY_ARG = {
     study: {
         type: "string",
@@ -138,6 +227,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 type: "object",
                 properties: {
                     query: { type: "string", description: "Words or phrase to find." },
+                    segment: { type: "string", description: "Optional. Restrict to one user segment." },
                     ...STUDY_ARG,
                 },
                 required: ["query"],
@@ -149,8 +239,9 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
             inputSchema: {
                 type: "object",
                 properties: {
-                    theme: { type: "string", description: "e.g. trust, onboarding, navigation" },
+                    theme: { type: "string", description: "e.g. trust, onboarding, navigation. Case-insensitive." },
                     round: { type: "number", description: "Optional: restrict to one research round." },
+                    segment: { type: "string", description: "Optional. Restrict to one user segment." },
                     ...STUDY_ARG,
                 },
                 required: ["theme"],
@@ -179,6 +270,50 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 required: ["theme"],
             },
         },
+        {
+            name: "release_readiness",
+            description: "Issues found in research, grouped by the severity the researcher tagged, with how many participants hit each and the quotes behind them. Answers 'what is still open before we ship'. Ends with what the evidence does not cover.",
+            inputSchema: { type: "object", properties: { ...STUDY_ARG } },
+        },
+        {
+            name: "track_metric",
+            description: "One measure across studies in date order: task completion or mean SUS, optionally split by segment. Answers 'did it improve since last release'. Reports each study separately and never averages across them.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    metric: { type: "string", description: "completion or sus. Defaults to both." },
+                    segment: { type: "string", description: "Optional. Restrict to one user segment." },
+                },
+            },
+        },
+        {
+            name: "prior_research",
+            description: "Which past studies already touched a topic, when, and with how many participants. Call this before commissioning new research so a question that has already been answered is not paid for twice.",
+            inputSchema: {
+                type: "object",
+                properties: { topic: { type: "string", description: "A theme, issue or phrase." } },
+                required: ["topic"],
+            },
+        },
+        {
+            name: "evidence_trail",
+            description: "Every piece of evidence behind one named issue, across all studies, with participant, study, release and date. Use when someone asks months later why a change was made, or when a decision has to be defensible to an auditor or regulator.",
+            inputSchema: {
+                type: "object",
+                properties: { issue: { type: "string", description: "Issue name, or a theme." } },
+                required: ["issue"],
+            },
+        },
+        {
+            name: "consent_status",
+            description: "What each participant agreed to, and what is therefore withheld. Shows the current audience setting, who has withdrawn, and whose quotes cannot be reproduced. Call this before putting quotes in anything that leaves the research team.",
+            inputSchema: { type: "object", properties: { ...STUDY_ARG } },
+        },
+        {
+            name: "coverage_gaps",
+            description: "Who has NOT been researched: segments and regions with thin or no evidence, and themes resting on very few participants. Answers 'whose experience are we guessing about'. The most important tool for anyone about to generalise a finding.",
+            inputSchema: { type: "object", properties: { ...STUDY_ARG } },
+        },
     ],
 }));
 server.setRequestHandler(CallToolRequestSchema, async (req) => {
@@ -199,16 +334,22 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
     const rows = allExcerpts(studies);
     const sessions = sessionsOf(studies);
     const multi = studies.length > 1;
+    // Rounds are only worth printing when a study actually ran more than one.
+    const showRound = new Set(sessions.map((x) => x.round ?? 1)).size > 1;
     const scope = args.study ? ` in "${args.study}"` : multi ? ` across ${studies.length} studies` : "";
     if (name === "list_studies") {
         const lines = all.map((st) => {
             const people = new Set(st.sessions.map((s) => s.id));
-            const rounds = [...new Set(st.sessions.map((s) => s.round))].sort();
+            const rounds = [...new Set(st.sessions.map((s) => s.round ?? 1))].sort();
             const segments = [...new Set(st.sessions.map((s) => s.segment))];
             const themes = [...new Set(st.sessions.flatMap((s) => s.excerpts.map((e) => e.theme)))];
             const quotes = st.sessions.reduce((a, s) => a + s.excerpts.length, 0);
             return (`${st.key}\n` +
                 `  name:         ${st.study?.name ?? "(unnamed)"}\n` +
+                (st.files.length > 1 ? `  merged from:  ${st.files.length} files (${st.files.join(", ")})\n` : "") +
+                (st.duplicates.length
+                    ? `  SKIPPED as duplicates: ${st.duplicates.join("; ")}\n`
+                    : "") +
                 `  participants: ${people.size}   sessions: ${st.sessions.length}   quotes: ${quotes}\n` +
                 `  rounds:       ${rounds.join(", ") || "none"}\n` +
                 `  segments:     ${segments.join(", ") || "none"}\n` +
@@ -222,28 +363,42 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
     }
     if (name === "search_transcripts") {
         const q = String(args.query ?? "").toLowerCase();
-        const hits = rows.filter((r) => r.quote.toLowerCase().includes(q) || r.theme.toLowerCase().includes(q));
+        const seg = applySegment(rows, args.segment);
+        const hits = seg.rows.filter((r) => r.quote.toLowerCase().includes(q) || r.theme.toLowerCase().includes(q));
         if (!hits.length)
-            return out(`No excerpts match "${args.query}"${scope}.`);
-        return out(`${hits.length} excerpt(s) matching "${args.query}"${scope}:\n\n` +
+            return out(`No excerpts match "${args.query}"${scope}${seg.label}.`);
+        return out(`${hits.length} excerpt(s) matching "${args.query}"${scope}${seg.label}:\n\n` +
             hits
-                .map((h) => `[${cite(h, multi)} | ${h.segment}] ${h.theme} / ${h.sentiment}\n  "${h.quote}"`)
+                .map((h) => `[${cite(h, multi, showRound)} | ${h.segment}] ${h.theme} / ${h.sentiment}\n  ${quoteOrWithheld(h)}`)
                 .join("\n\n"));
     }
     if (name === "quotes_by_theme") {
-        let hits = rows.filter((r) => r.theme === args.theme);
+        const seg = applySegment(rows, args.segment);
+        let hits = seg.rows.filter((r) => themeMatches(r.theme, args.theme));
         if (typeof args.round === "number")
-            hits = hits.filter((r) => r.round === args.round);
-        if (!hits.length)
-            return out(`No quotes tagged "${args.theme}"${scope}.`);
+            hits = hits.filter((r) => (r.round ?? 1) === args.round);
+        if (!hits.length) {
+            // Distinguish "that theme does not exist" from "it exists, just not in
+            // that segment". Conflating them reads as an absence of evidence.
+            const themeExists = rows.some((r) => themeMatches(r.theme, args.theme));
+            if (themeExists && args.segment) {
+                const segs = [
+                    ...new Set(rows.filter((r) => themeMatches(r.theme, args.theme)).map((r) => r.segment)),
+                ];
+                return out(`"${args.theme}" was raised${scope}, but not by any participant in segment "${args.segment}".\n` +
+                    `Segments that did raise it: ${segs.join(", ")}.\n` +
+                    `That the segment did not raise it is not evidence they do not care. They may not have been asked.`);
+            }
+            return out(`No quotes tagged "${args.theme}"${scope}${seg.label}.` + themeSuggestion(rows, args.theme));
+        }
         const groups = { positive: [], negative: [], mixed: [] };
         hits.forEach((h) => groups[h.sentiment]?.push(h));
         const body = Object.entries(groups)
             .filter(([, v]) => v.length)
             .map(([k, v]) => `${k.toUpperCase()} (${v.length})\n` +
-            v.map((h) => `  [${cite(h, multi)}] "${h.quote}"`).join("\n"))
+            v.map((h) => `  [${cite(h, multi, showRound)}] ${quoteOrWithheld(h)}`).join("\n"))
             .join("\n\n");
-        return out(`Theme "${args.theme}"${scope} — ${hits.length} excerpt(s)\n\n${body}`);
+        return out(`Theme "${args.theme}"${scope}${seg.label} — ${hits.length} excerpt(s)\n\n${body}`);
     }
     if (name === "pattern_frequency") {
         // Counts are never pooled across studies. Different studies have different
@@ -251,7 +406,10 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
         // would be a number that looks like evidence and is not one.
         const perStudy = (st) => {
             const rws = allExcerpts([st]);
-            const total = new Set(st.sessions.map((s) => s.id)).size;
+            // active(), not st.sessions: a withdrawn participant must not sit in a
+            // denominator. Leaving them in silently understates every percentage.
+            const live = active(st.sessions);
+            const total = new Set(live.map((s) => s.id)).size;
             if (!total)
                 return `${st.key}: no sessions.`;
             const byTheme = {};
@@ -268,7 +426,7 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
                     .join(", ");
                 return `  ${theme}: ${set.size}/${total} participants (${seg})`;
             });
-            return `${st.key} — ${st.sessions.length} sessions\n${lines.join("\n")}`;
+            return `${st.key} — ${live.length} sessions\n${lines.join("\n")}`;
         };
         if (!sessions.length)
             return out(`No sessions${scope}.`);
@@ -288,13 +446,17 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
             return out(`Rounds can only be compared within one study. Name one of: ${all.map((s) => s.key).join(", ")}.`);
         }
         const theme = String(args.theme);
-        const rounds = [...new Set(sessions.map((s) => s.round))].sort((a, b) => a - b);
+        // round is optional in the data; loadAll defaults it, but narrow for the type
+        const rounds = [...new Set(sessions.map((s) => s.round ?? 1))].sort((a, b) => a - b);
         if (rounds.length < 2) {
-            return out(`Only round ${rounds[0] ?? "none"} exists${scope}, so there is nothing to compare.`);
+            return out(rounds.length === 0
+                ? `No sessions${scope}, so there is nothing to compare.`
+                : `This study has a single round${scope}, so there is nothing to compare. ` +
+                    `compare_rounds is for studies run before and after a design change.`);
         }
         const summarise = (round) => {
-            const hits = rows.filter((r) => r.theme === theme && r.round === round);
-            const ss = sessions.filter((s) => s.round === round);
+            const hits = rows.filter((r) => r.theme === theme && (r.round ?? 1) === round);
+            const ss = sessions.filter((s) => (s.round ?? 1) === round);
             const scored = ss.filter((s) => typeof s.sus === "number" && s.sus > 0);
             return {
                 pos: hits.filter((h) => h.sentiment === "positive").length,
@@ -304,17 +466,32 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
                 sus: scored.length ? Math.round(scored.reduce((a, s) => a + s.sus, 0) / scored.length) : null,
             };
         };
-        const first = summarise(rounds[0]);
-        const last = summarise(rounds[rounds.length - 1]);
+        const perRound = rounds.map(summarise);
+        const first = perRound[0];
+        const last = perRound[perRound.length - 1];
         const susLine = (r) => (r.sus === null ? "not recorded" : String(r.sus));
         const susDelta = first.sus !== null && last.sus !== null
             ? `SUS ${last.sus - first.sus >= 0 ? "+" : ""}${last.sus - first.sus}`
             : "SUS not comparable";
-        return out(`Theme "${theme}"${scope}, round ${rounds[0]} vs round ${rounds[rounds.length - 1]}\n\n` +
-            `Round ${rounds[0]}: ${first.pos} positive / ${first.neg} negative | completed ${first.done}/${first.n} | mean SUS ${susLine(first)}\n` +
-            `Round ${rounds[rounds.length - 1]}: ${last.pos} positive / ${last.neg} negative | completed ${last.done}/${last.n} | mean SUS ${susLine(last)}\n\n` +
-            `Direction: sentiment ${last.pos - first.pos >= 0 ? "improved" : "declined"}, ${susDelta}.\n` +
-            `Caution: ${first.n + last.n} sessions is a small n. Treat as directional, not significant.`);
+        // Every round is listed. With three or more, reporting only the first and
+        // last would silently hide a regression in the middle.
+        const header = rounds.length === 2
+            ? `round ${rounds[0]} vs round ${rounds[1]}`
+            : `rounds ${rounds.join(", ")}`;
+        const body = rounds
+            .map((rd, i) => {
+            const r = perRound[i];
+            return `Round ${rd}: ${r.pos} positive / ${r.neg} negative | completed ${r.done}/${r.n} | mean SUS ${susLine(r)}`;
+        })
+            .join("\n");
+        const totalSessions = perRound.reduce((a, r) => a + r.n, 0);
+        return out(`Theme "${theme}"${scope}, ${header}\n\n` +
+            body +
+            `\n\nDirection: sentiment ${last.pos - first.pos >= 0 ? "improved" : "declined"}, ${susDelta}.\n` +
+            `Caution: ${totalSessions} sessions is a small n. Treat as directional, not significant.` +
+            (rounds.length > 2
+                ? `\nDirection compares round ${rounds[0]} with round ${rounds[rounds.length - 1]} only. Read the middle rounds above before concluding it improved throughout.`
+                : ""));
     }
     if (name === "draft_findings") {
         // A finding belongs to a study. Drafting one over pooled studies would put a
@@ -323,9 +500,10 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
             return out(`A finding is drafted from one study at a time, so the participant count means something. Name one of: ${all.map((s) => s.key).join(", ")}.`);
         }
         const theme = String(args.theme);
-        const hits = rows.filter((r) => r.theme === theme);
+        const hits = rows.filter((r) => themeMatches(r.theme, theme));
         if (!hits.length)
-            return out(`No evidence tagged "${theme}"${scope}, so no finding can be drafted.`);
+            return out(`No evidence tagged "${theme}"${scope}, so no finding can be drafted.` +
+                themeSuggestion(rows, theme));
         const people = new Set(hits.map((h) => h.participant));
         const total = new Set(sessions.map((s) => s.id)).size;
         const neg = hits.filter((h) => h.sentiment === "negative");
@@ -333,7 +511,7 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
         const mix = hits.filter((h) => h.sentiment === "mixed");
         const block = (label, v) => v.length
             ? `${label} (${v.length}):\n` +
-                v.map((h) => `  [${cite(h, multi)}] "${h.quote}"`).join("\n") +
+                v.map((h) => `  [${cite(h, multi, showRound)}] ${quoteOrWithheld(h)}`).join("\n") +
                 "\n"
             : "";
         return out(`DRAFT FINDING — ${theme}${scope}\n\n` +
@@ -350,6 +528,221 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
             `  Any causal claim. This is correlation in a small sample.\n\n` +
             `The researcher writes the recommendation. This tool supplies evidence and its limits.`);
     }
+    // ---------------------------------------------------------------------
+    // Tools for teams who have to make a release decision, not just read a
+    // report. They still only retrieve and count. What they add is the honest
+    // other half: what the evidence does NOT cover.
+    // ---------------------------------------------------------------------
+    const studyLabel = (st) => {
+        const bits = [st.study?.product, st.study?.release, st.study?.date].filter(Boolean);
+        return bits.length ? `${st.key} (${bits.join(", ")})` : st.key;
+    };
+    if (name === "release_readiness") {
+        if (!rows.length)
+            return out(`No evidence${scope}.`);
+        const people = new Set(sessions.map((s) => s.id)).size;
+        const tagged = rows.filter((r) => r.severity);
+        if (!tagged.length) {
+            return out(`No severity tags${scope}, so this cannot report readiness.\n\n` +
+                `Add "severity": "blocker" | "major" | "minor" to the excerpts that represent problems. ` +
+                `Severity is the researcher's judgment, which is why this tool reads it rather than deciding it.`);
+        }
+        // Group by issue where tagged, otherwise fall back to the theme.
+        const byIssue = {};
+        tagged.forEach((r) => ((byIssue[r.issue || r.theme] ??= []).push(r)));
+        const sections = SEVERITY_ORDER.map((sev) => {
+            const issues = Object.entries(byIssue)
+                .filter(([, v]) => v.some((r) => r.severity === sev))
+                .map(([issue, v]) => {
+                const hits = v.filter((r) => r.severity === sev);
+                const who = new Set(hits.map((h) => h.participant));
+                const segs = [...new Set(hits.map((h) => h.segment))];
+                const quotes = hits
+                    .slice(0, 3)
+                    .map((h) => `      [${cite(h, multi, showRound)}] ${quoteOrWithheld(h)}`)
+                    .join("\n");
+                return {
+                    n: who.size,
+                    text: `   ${issue}: ${who.size} of ${people} participants (${segs.join(", ")})\n` +
+                        quotes +
+                        (hits.length > 3 ? `\n      ...and ${hits.length - 3} more` : ""),
+                };
+            })
+                .sort((a, b) => b.n - a.n);
+            if (!issues.length)
+                return null;
+            const total = new Set(tagged.filter((r) => r.severity === sev).map((r) => r.participant)).size;
+            return `${sev.toUpperCase()} — ${issues.length} issue(s), ${total} participant(s) affected\n${issues
+                .map((i) => i.text)
+                .join("\n\n")}`;
+        }).filter(Boolean);
+        const segs = [...new Set(sessions.map((s) => s.segment))];
+        const regions = [...new Set(sessions.map((s) => s.region).filter(Boolean))];
+        const thin = segs.filter((sg) => sessions.filter((s) => s.segment === sg).length < 5);
+        return out(`RELEASE READINESS${scope}\n` +
+            `Evidence from ${studies.length} study/studies, ${people} participants, ${sessions.length} sessions.\n` +
+            studies.map((st) => `  ${studyLabel(st)}`).join("\n") +
+            `\n\n${sections.join("\n\n")}\n\n` +
+            `WHAT THIS IS NOT\n` +
+            `  Not a ship decision. It counts participants who hit an issue; it does not weigh that against revenue, deadline or effort.\n` +
+            `  Not a severity judgment. Severity is read from the researcher's tags, not inferred.\n` +
+            `  Not frequency in the wild. ${people} participants in a lab is not ${people} percent of customers.\n\n` +
+            `THIN EVIDENCE, TREAT WITH CARE\n` +
+            (thin.length
+                ? thin
+                    .map((sg) => `  ${sg}: only ${sessions.filter((s) => s.segment === sg).length} participant(s)`)
+                    .join("\n")
+                : `  Every segment has 5 or more participants.`) +
+            (regions.length ? `\n  Regions covered: ${regions.join(", ")}` : `\n  No region recorded on any session.`));
+    }
+    if (name === "track_metric") {
+        const want = String(args.metric ?? "").toLowerCase();
+        const seg = args.segment ? String(args.segment).toLowerCase() : null;
+        const dated = [...all].sort((a, b) => String(a.study?.date ?? "").localeCompare(String(b.study?.date ?? "")));
+        const lines = dated.map((st) => {
+            let ss = st.sessions;
+            if (seg)
+                ss = ss.filter((s) => s.segment.toLowerCase() === seg);
+            if (!ss.length)
+                return `${studyLabel(st)}: no sessions${seg ? ` for segment "${args.segment}"` : ""}`;
+            const scored = ss.filter((s) => typeof s.sus === "number" && s.sus > 0);
+            const completion = `${ss.filter((s) => s.completed).length}/${ss.length}`;
+            const sus = scored.length
+                ? Math.round(scored.reduce((a, s) => a + s.sus, 0) / scored.length)
+                : null;
+            const parts = [];
+            if (!want || want.includes("complet"))
+                parts.push(`completion ${completion}`);
+            if (!want || want.includes("sus"))
+                parts.push(`mean SUS ${sus === null ? "not recorded" : sus}`);
+            return `${studyLabel(st)}: ${parts.join(" | ")}  (n=${ss.length})`;
+        });
+        return out(`Metric over time${seg ? `, segment "${args.segment}"` : ""}, oldest first\n\n` +
+            lines.join("\n") +
+            `\n\nStudies are listed separately and never averaged together. Different participants, recruitment and tasks.\n` +
+            (dated.some((st) => !st.study?.date)
+                ? `Some studies have no "date" in their study block, so this order may be wrong. Add one to fix it.`
+                : `Ordered by the "date" field on each study.`));
+    }
+    if (name === "prior_research") {
+        const q = String(args.topic ?? "").toLowerCase();
+        const found = all
+            .map((st) => {
+            const rws = allExcerpts([st]).filter((r) => r.theme.toLowerCase().includes(q) ||
+                r.quote.toLowerCase().includes(q) ||
+                (r.issue ?? "").toLowerCase().includes(q));
+            return { st, rws, people: new Set(rws.map((r) => r.participant)) };
+        })
+            .filter((x) => x.rws.length);
+        if (!found.length) {
+            return out(`No existing study in this repository covers "${args.topic}".\n\n` +
+                `Searched ${all.length} study/studies: ${all.map((s) => s.key).join(", ")}.\n` +
+                `Absence here means nobody filed it, which is not the same as nobody having asked. Check outside the repository before concluding it is unresearched.`);
+        }
+        return out(`"${args.topic}" has already been researched in ${found.length} study/studies\n\n` +
+            found
+                .map((x) => `${studyLabel(x.st)}\n` +
+                `  ${x.people.size} participant(s), ${x.rws.length} excerpt(s)\n` +
+                `  themes: ${[...new Set(x.rws.map((r) => r.theme))].join(", ")}\n` +
+                `  e.g. [${cite({ ...x.rws[0], study: x.st.key }, true, showRound)}] ${quoteOrWithheld(x.rws[0])}`)
+                .join("\n\n") +
+            `\n\nRead these before commissioning new research on the topic.`);
+    }
+    if (name === "evidence_trail") {
+        const q = String(args.issue ?? "").toLowerCase();
+        const hits = allExcerpts(all).filter((r) => (r.issue ?? "").toLowerCase() === q || r.theme.toLowerCase() === q ||
+            (r.issue ?? "").toLowerCase().includes(q));
+        if (!hits.length) {
+            return out(`No evidence filed under "${args.issue}" in any study.`);
+        }
+        const byStudy = {};
+        hits.forEach((h) => ((byStudy[h.study] ??= []).push(h)));
+        const people = new Set(hits.map((h) => h.participant));
+        return out(`EVIDENCE TRAIL — ${args.issue}\n` +
+            `${hits.length} excerpt(s) from ${people.size} participant(s), across ${Object.keys(byStudy).length} study/studies.\n\n` +
+            Object.entries(byStudy)
+                .map(([key, v]) => {
+                const st = all.find((s) => s.key === key);
+                return (`${studyLabel(st)}\n` +
+                    v
+                        .map((h) => `  [${h.participant} | R${h.round} | ${h.t}] ${h.segment}` +
+                        (h.severity ? ` | ${h.severity}` : "") +
+                        `\n    ${quoteOrWithheld(h)}`)
+                        .join("\n"));
+            })
+                .join("\n\n") +
+            `\n\nEvery line above is a participant's own words with the session it came from. Nothing here is summarised or rephrased.`);
+    }
+    if (name === "consent_status") {
+        const everySession = studies.flatMap((st) => st.sessions.map((x) => ({ ...x, study: st.key })));
+        if (!everySession.length)
+            return out(`No sessions${scope}.`);
+        const group = {
+            full: [], internal: [], counts: [], withdrawn: [],
+        };
+        everySession.forEach((x) => group[consentOf(x)].push(x));
+        const line = (x) => `  ${x.id}${multi ? ` (${x.study})` : ""}${x.consent_note ? ` — ${x.consent_note}` : ""}`;
+        const section = (c, explain) => group[c].length ? `${c.toUpperCase()} (${group[c].length}) — ${explain}\n${group[c].map(line).join("\n")}` : "";
+        const withheld = everySession.filter((x) => consentOf(x) !== "withdrawn" && !mayQuote(consentOf(x))).length;
+        return out(`CONSENT${scope}\n` +
+            `Audience: ${AUDIENCE === "team" ? "research team (RESEARCH_LENS_AUDIENCE unset or \"team\")" : "external (RESEARCH_LENS_AUDIENCE=external)"}\n` +
+            `${everySession.length} participants on file, ${group.withdrawn.length} withdrawn, ` +
+            `${withheld} whose quotes are withheld at this audience setting.\n\n` +
+            [
+                section("full", "quotes may be reproduced"),
+                section("internal", `quotes shown to the research team only${AUDIENCE === "external" ? ", withheld here" : ""}`),
+                section("counts", "counted, never quoted"),
+                section("withdrawn", "removed from every count, quote and denominator"),
+            ]
+                .filter(Boolean)
+                .join("\n\n") +
+            `\n\nHOW THIS IS ENFORCED\n` +
+            `  Withdrawn participants are removed before anything is counted, so they do not sit in a denominator.\n` +
+            `  A withheld quote is always labelled as withheld, never silently dropped. "Nobody said this" and "someone said this and did not consent to it leaving" must never look the same.\n` +
+            `  Consent is read from the data. This server never infers it, and a participant with no consent field is treated as "full", which is how studies recorded before consent tracking behave.\n` +
+            `  Set RESEARCH_LENS_AUDIENCE=external when the output will leave the research team.`);
+    }
+    if (name === "coverage_gaps") {
+        if (!sessions.length)
+            return out(`No sessions${scope}.`);
+        const people = new Set(sessions.map((s) => s.id)).size;
+        const bySeg = {};
+        const byRegion = {};
+        sessions.forEach((s) => {
+            (bySeg[s.segment] ??= new Set()).add(s.id);
+            if (s.region)
+                (byRegion[s.region] ??= new Set()).add(s.id);
+        });
+        const byTheme = {};
+        rows.forEach((r) => (byTheme[r.theme] ??= new Set()).add(r.participant));
+        const fragile = Object.entries(byTheme)
+            .filter(([, v]) => v.size <= 2)
+            .sort((a, b) => a[1].size - b[1].size);
+        const thinSeg = Object.entries(bySeg).filter(([, v]) => v.size < 5);
+        return out(`COVERAGE GAPS${scope}\n${people} participants across ${sessions.length} sessions.\n\n` +
+            `SEGMENTS\n` +
+            Object.entries(bySeg)
+                .sort((a, b) => b[1].size - a[1].size)
+                .map(([k, v]) => `  ${k}: ${v.size}`)
+                .join("\n") +
+            (thinSeg.length
+                ? `\n  Thin: ${thinSeg.map(([k, v]) => `${k} (${v.size})`).join(", ")}. A finding about these rests on very few people.`
+                : `\n  No segment below 5 participants.`) +
+            `\n\nREGIONS\n` +
+            (Object.keys(byRegion).length
+                ? Object.entries(byRegion)
+                    .map(([k, v]) => `  ${k}: ${v.size}`)
+                    .join("\n")
+                : `  No region recorded on any session, so nothing can be said about geographic coverage.`) +
+            `\n\nTHEMES RESTING ON 1 OR 2 PARTICIPANTS\n` +
+            (fragile.length
+                ? fragile.map(([k, v]) => `  ${k}: ${v.size}`).join("\n") +
+                    `\n  These are leads, not findings. Do not put them in a readout as patterns.`
+                : `  Every theme has 3 or more participants behind it.`) +
+            `\n\nWHAT IS MISSING ENTIRELY\n` +
+            `  This tool can only report on people who were recruited. Anyone your recruitment never reached is invisible here, ` +
+            `including non-users, people who gave up before becoming customers, and anyone screened out. That is usually the biggest gap and no tool can show it to you.`);
+    }
     return out(`Unknown tool: ${name}`);
 });
 const transport = new StdioServerTransport();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "research-lens-mcp",
-  "version": "2.0.0",
+  "version": "2.3.0",
   "description": "An MCP server that lets an AI assistant query a UX research repository with participant-level citations attached. It retrieves and counts; it does not interpret.",
   "type": "module",
   "bin": {
@@ -32,7 +32,12 @@
     "claude",
     "ai-research",
     "synthesis",
-    "usability-testing"
+    "usability-testing",
+    "consent",
+    "gdpr",
+    "research-ethics",
+    "irb",
+    "participant-consent"
   ],
   "license": "MIT",
   "author": "Siddhi Manche",