research-lens-mcp 2.2.0 → 2.3.0

package/README.md

@@ -139,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
 {
@@ -172,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

@@ -59,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 {
@@ -83,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,
@@ -114,6 +135,9 @@ function allExcerpts(studies) {
         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) => active(s.sessions));
@@ -178,8 +202,11 @@ function applySegment(rows, segment) {
     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.2.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",
@@ -307,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` +
@@ -336,14 +369,14 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
             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  ${quoteOrWithheld(h)}`)
+                .map((h) => `[${cite(h, multi, showRound)} | ${h.segment}] ${h.theme} / ${h.sentiment}\n  ${quoteOrWithheld(h)}`)
                 .join("\n\n"));
     }
     if (name === "quotes_by_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);
+            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.
@@ -363,7 +396,7 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
         const body = Object.entries(groups)
             .filter(([, v]) => v.length)
             .map(([k, v]) => `${k.toUpperCase()} (${v.length})\n` +
-            v.map((h) => `  [${cite(h, multi)}] ${quoteOrWithheld(h)}`).join("\n"))
+            v.map((h) => `  [${cite(h, multi, showRound)}] ${quoteOrWithheld(h)}`).join("\n"))
             .join("\n\n");
         return out(`Theme "${args.theme}"${scope}${seg.label} — ${hits.length} excerpt(s)\n\n${body}`);
     }
@@ -413,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,
@@ -474,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)}] ${quoteOrWithheld(h)}`).join("\n") +
+                v.map((h) => `  [${cite(h, multi, showRound)}] ${quoteOrWithheld(h)}`).join("\n") +
                 "\n"
             : "";
         return out(`DRAFT FINDING — ${theme}${scope}\n\n` +
@@ -522,7 +559,7 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
                 const segs = [...new Set(hits.map((h) => h.segment))];
                 const quotes = hits
                     .slice(0, 3)
-                    .map((h) => `      [${cite(h, multi)}] ${quoteOrWithheld(h)}`)
+                    .map((h) => `      [${cite(h, multi, showRound)}] ${quoteOrWithheld(h)}`)
                     .join("\n");
                 return {
                     n: who.size,
@@ -607,7 +644,7 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
                 .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)}] ${quoteOrWithheld(x.rws[0])}`)
+                `  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.`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "research-lens-mcp",
-  "version": "2.2.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": {