research-lens-mcp 0.0.0-stage → 2.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,112 @@
1
+ # Loading a new study into Research Lens
2
+
3
+ Two ways in. Both end with the same `data/sessions.json`, and neither needs a restart.
4
+
5
+ - **A** You already have structured notes → fill in `template.csv`, run one command.
6
+ - **B** You have raw transcripts → paste the prompt below into Claude and let it do the
7
+ tagging, with you approving it.
8
+
9
+ ---
10
+
11
+ ## A. From a spreadsheet
12
+
13
+ Open `template.csv` in Excel, Numbers or Google Sheets. One row per quote. Fill down the
14
+ participant columns so every row for a person repeats their details.
15
+
16
+ | Column | What goes in it | Required |
17
+ |---|---|---|
18
+ | participant | P01, P02 … | yes |
19
+ | round | 1, 2 … | yes |
20
+ | segment | the user group, e.g. "new user" | yes |
21
+ | task | what you asked them to do | no |
22
+ | completed | yes / no | no |
23
+ | sus | their SUS score, blank if none | no |
24
+ | timestamp | 04:12 | no |
25
+ | theme | what the quote is about | yes |
26
+ | sentiment | positive, negative or mixed | yes |
27
+ | quote | their words, verbatim | yes |
28
+
29
+ Save as CSV, then:
30
+
31
+ ```bash
32
+ npm run import my-study.csv "Study name" "IRB number"
33
+ ```
34
+
35
+ It backs up the old data, refuses to write anything if a row is malformed, and tells you
36
+ exactly which row is wrong. Then just ask Claude Desktop a question.
37
+
38
+ ---
39
+
40
+ ## B. From raw transcripts, with a prompt
41
+
42
+ Put your transcript files in a folder. Open Claude Code in the project, or Cowork with the
43
+ folder connected, and paste everything below the line.
44
+
45
+ ---
46
+
47
+ You are helping me load a UX study into Research Lens, an MCP server that answers questions
48
+ about a research repository. Your job is to turn raw transcripts into one CSV row per
49
+ meaningful quote. Read `INGEST_PROMPT.md` and `template.csv` in this project first so you
50
+ match the format exactly.
51
+
52
+ **The rule that matters most: every quote must be the participant's actual words, copied
53
+ from the transcript.** Do not paraphrase, tidy, shorten or improve them. Do not write a
54
+ quote that is not in the source. If a line is unclear, leave it out and tell me, rather than
55
+ guessing what they meant. A repository full of invented quotes is worse than no repository.
56
+
57
+ Work in this order, and stop at each checkpoint.
58
+
59
+ **1. Tell me what you found.** How many transcripts, how many participants, and whether each
60
+ one tells you the round, the user segment, the task, completion and a SUS score. List what is
61
+ missing. Ask me for anything you cannot read off the files. Do not guess a segment from
62
+ someone's name or how they talk.
63
+
64
+ **2. Propose a theme list, then stop.** Read everything, then suggest 4 to 8 themes that
65
+ cover what people actually talked about, with a one-line definition of each and a rough
66
+ count of how many participants touched it. Themes should describe the subject, not the
67
+ verdict: "onboarding", not "onboarding is confusing". Wait for me to approve, rename or
68
+ merge them before you tag anything.
69
+
70
+ **3. Tag the quotes.** Once themes are agreed, pull every quote that carries evidence about
71
+ one of them. Skip small talk, moderator speech and anything that is just task narration.
72
+ For each, record the timestamp if the transcript has one, the theme, and a sentiment of
73
+ positive, negative or mixed. Sentiment is about the experience being described, not the
74
+ person's tone. If you are unsure between two sentiments, use mixed and flag it.
75
+
76
+ **4. Show me the ones you were unsure about, then stop.** Before writing anything, list
77
+ every quote where the theme or sentiment was a judgment call, with your reasoning in one
78
+ line each. I will correct them. Do not skip this step, even if the list is short, and do not
79
+ hide uncertainty by picking the safer label.
80
+
81
+ **5. Write the file and verify.** Save as `study.csv` in the project root in exactly the
82
+ `template.csv` column order, then run:
83
+
84
+ ```bash
85
+ npm run import study.csv "<study name>" "<IRB number or blank>"
86
+ ```
87
+
88
+ Report what the importer printed. If it found problems, fix those rows and run it again.
89
+ Then run `node docs/build.mjs` so the demo page shows the new study too.
90
+
91
+ **6. Hand it back to me.** Tell me how many participants, sessions and quotes went in, and
92
+ the participant count per theme. Then stop. Do not tell me what the findings mean, do not
93
+ write recommendations, and do not describe anything as a problem users have. That judgment
94
+ is mine, and the whole point of this tool is that it supplies evidence rather than
95
+ conclusions.
96
+
97
+ **Anonymising:** replace real names with P01, P02 and so on, consistently. Strip employers,
98
+ locations, email addresses and anything else that could identify someone. If a quote cannot
99
+ be anonymised without changing its words, leave it out and tell me which one.
100
+
101
+ ---
102
+
103
+ ## Why the tagging is not a tool on the server
104
+
105
+ The server has five tools and none of them tag anything. That is deliberate. Deciding a
106
+ quote is "about trust" and "negative" is interpretation, and interpretation is the thing the
107
+ researcher is responsible for.
108
+
109
+ Keeping it out here means an AI can suggest the tags, quickly, over a lot of material, but a
110
+ person signs off before any of it gets counted. Once tagged data is in the repository, the
111
+ server only ever retrieves and counts it. The line is: AI proposes, the researcher decides,
112
+ the tool keeps score.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Siddhi Manche
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,207 @@
1
- # Temporary Holding Version
1
+ # Research Lens
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ **An MCP server that lets an AI assistant query your UX research repository — with the participant ID attached to every claim.**
4
+
5
+ [Try the live demo](https://siddhidesign.github.io/Research-Lens/) · [Install](#install) · [Format](#your-data) · [Why it refuses to interpret](#the-constraint)
6
+
7
+ ```
8
+ You: Did trust improve between round one and round two?
9
+
10
+ Theme "trust", round 1 vs round 2
11
+
12
+ Round 1: 0 positive / 1 negative | completed 1/3 | mean SUS 55
13
+ Round 2: 2 positive / 0 negative | completed 3/3 | mean SUS 81
14
+
15
+ Direction: sentiment improved, SUS +26.
16
+ Caution: 6 sessions is a small n. Treat as directional, not significant.
17
+ ```
18
+
19
+ That last line is the point.
20
+
21
+ ---
22
+
23
+ ## The problem
24
+
25
+ You finish twelve interviews. Now someone asks how many people struggled with signup, and whether the redesign helped.
26
+
27
+ The usual answer is copy and paste: move transcript chunks into a chat window, let the model summarise. Two things go wrong, and neither is the model's fault.
28
+
29
+ **It only sees what you pasted.** So it cannot tell you how many participants raised a theme, or whether round two beat round one. It can only describe the fragment in front of it, confidently.
30
+
31
+ **The output has no citations.** You get a fluent paragraph about what "users" want. You cannot trace a single claim back to a person, which means you cannot defend it when a stakeholder asks "says who?"
32
+
33
+ That is not a model problem. It is an access problem.
34
+
35
+ ## What this does
36
+
37
+ Research Lens gives the assistant direct, structured access to your repository. You ask questions in plain language; it queries the actual data.
38
+
39
+ | Ask | Tool | You get |
40
+ |---|---|---|
41
+ | "What's in my repository?" | `list_studies` | Every study, its participants, rounds, segments and themes |
42
+ | "Did anyone mention pricing?" | `search_transcripts` | Matching quotes, each with participant, round and timestamp |
43
+ | "Show me everything about trust" | `quotes_by_theme` | Verbatim quotes grouped by sentiment |
44
+ | "Is this a real pattern?" | `pattern_frequency` | Distinct participants per theme, split by segment |
45
+ | "Did the redesign work?" | `compare_rounds` | Sentiment, completion and SUS, round over round |
46
+ | "Draft a finding on onboarding" | `draft_findings` | Evidence with citations, plus what the data does not support |
47
+
48
+ Teams shipping on a release schedule, and anyone whose decisions have to survive an audit, get five more:
49
+
50
+ | Ask | Tool | You get |
51
+ |---|---|---|
52
+ | "What's still open before we ship?" | `release_readiness` | Issues by the severity you tagged, participants affected, quotes behind each |
53
+ | "Did it improve since last release?" | `track_metric` | Completion and SUS per study in date order, never averaged across studies |
54
+ | "Has anyone studied this already?" | `prior_research` | Which past studies touched a topic, when, with how many participants |
55
+ | "Why did we make that change?" | `evidence_trail` | Every verbatim quote behind one issue, with participant, study, release and date |
56
+ | "Whose experience are we guessing about?" | `coverage_gaps` | Segments, regions and themes resting on too few people |
57
+
58
+ `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.
59
+
60
+ ## The constraint
61
+
62
+ **The server retrieves and counts. It does not interpret.**
63
+
64
+ That line is enforced, not aspirational, and it shows up in four places:
65
+
66
+ **Citations are mandatory.** Every excerpt returns as `[P14 | R2 | 08:47]`. A finding you cannot trace is a finding you cannot defend.
67
+
68
+ **It counts participants, not quotes.** Three quotes from one enthusiastic person is not a pattern. `pattern_frequency` counts distinct people and splits by segment, which is how you discover that a complaint belongs to new users only.
69
+
70
+ **It says what it cannot tell you.** `draft_findings` ends with a NOT SUPPORTED section: no causal claims, no generalising past the sample. An AI that sounds certain about six participants is a liability.
71
+
72
+ **It refuses to pool across studies.** Ask for a finding while two studies are loaded and it declines, because "5 of 8 participants" across two unrelated studies is a number that looks like evidence and is not one. Different recruitment, different questions, different people.
73
+
74
+ 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.
75
+
76
+ ## Consent, enforced at the point of query
77
+
78
+ Research platforms manage consent at the storage layer: who can log into the tool. Research
79
+ Lens enforces it at the **query** layer, where an AI agent actually reads. Each participant
80
+ carries what they agreed to, and the server obeys it.
81
+
82
+ | Consent | What happens |
83
+ |---|---|
84
+ | `full` | Quotes reproduced normally. The default, so existing studies are unaffected. |
85
+ | `internal` | Quotes shown to the research team, withheld when the output is external. |
86
+ | `counts` | Counted in every pattern, never quoted. They agreed to be studied, not published. |
87
+ | `withdrawn` | Removed from every count, quote and **denominator**. |
88
+
89
+ Set `RESEARCH_LENS_AUDIENCE=external` when the answer will leave the research team.
90
+
91
+ A withheld quote is always labelled:
92
+
93
+ ```
94
+ MIXED (1)
95
+ [P07 | R1 | 02:55] [quote withheld: consented to research-team use only, and this output is external]
96
+ ```
97
+
98
+ It is never silently dropped. "Nobody said this" and "someone said this and did not consent
99
+ to it leaving" must never look the same, because one is a finding and the other is a
100
+ compliance breach wearing a finding's clothes.
101
+
102
+ `consent_status` reports who agreed to what, who withdrew, and what is being withheld right
103
+ now. Consent is read from the data and never inferred.
104
+
105
+ ## Install
106
+
107
+ **Claude Desktop.** Open your config:
108
+
109
+ - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
110
+ - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
111
+
112
+ Add this inside `mcpServers`:
113
+
114
+ ```json
115
+ {
116
+ "mcpServers": {
117
+ "research-lens": {
118
+ "command": "npx",
119
+ "args": ["-y", "research-lens-mcp"],
120
+ "env": {
121
+ "RESEARCH_LENS_DATA": "/absolute/path/to/your/studies"
122
+ }
123
+ }
124
+ }
125
+ }
126
+ ```
127
+
128
+ Restart Claude Desktop. Leave out the `env` block to try it against the bundled sample study first.
129
+
130
+ **Claude Code**
131
+
132
+ ```bash
133
+ claude mcp add research-lens -e RESEARCH_LENS_DATA=/path/to/studies -- npx -y research-lens-mcp
134
+ ```
135
+
136
+ **Any other MCP client:** the command is `npx -y research-lens-mcp` over stdio.
137
+
138
+ Node 18 or newer. Nothing to clone, nothing to build.
139
+
140
+ ## Your data
141
+
142
+ `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.
143
+
144
+ ```json
145
+ {
146
+ "study": { "name": "Refund flow usability test", "irb": "optional" },
147
+ "sessions": [
148
+ {
149
+ "id": "P01",
150
+ "round": 1,
151
+ "segment": "new user",
152
+ "task": "find a refund",
153
+ "completed": false,
154
+ "sus": 52,
155
+ "excerpts": [
156
+ {
157
+ "t": "04:12",
158
+ "theme": "navigation",
159
+ "sentiment": "negative",
160
+ "quote": "I could not tell which button actually submits."
161
+ }
162
+ ]
163
+ }
164
+ ]
165
+ }
166
+ ```
167
+
168
+ Only `id`, `round`, `segment` and the excerpt fields are required. Everything else is optional and degrades gracefully: no SUS scores means `compare_rounds` reports "not recorded" rather than inventing a number.
169
+
170
+ ### Getting your data in
171
+
172
+ **From a spreadsheet.** Fill in [`template.csv`](template.csv), one row per quote, then:
173
+
174
+ ```bash
175
+ npx research-lens-mcp-import my-study.csv "Study name"
176
+ ```
177
+
178
+ It validates every row, names the row and the reason if something is wrong, and writes nothing until the file is clean.
179
+
180
+ **From raw transcripts.** [`INGEST_PROMPT.md`](INGEST_PROMPT.md) is a prompt you hand to Claude along with your transcripts. It proposes a theme list and stops for your approval, tags the quotes, then shows you every judgment call before writing anything. It is instructed to use verbatim quotes only and to anonymise as it goes.
181
+
182
+ Tagging lives in that prompt rather than in the server on purpose. Deciding a quote is "about trust" and "negative" is interpretation, and interpretation is the researcher's job. AI proposes, the researcher decides, the tool keeps score.
183
+
184
+ ## How it is kept honest
185
+
186
+ The [demo page](https://siddhidesign.github.io/Research-Lens/) reimplements the tools in the browser so you can read the raw responses without installing anything. That creates a drift risk — the page could start saying something the server does not.
187
+
188
+ So `npm run verify` spawns the real server over stdio, calls every tool with the same arguments the page uses, and fails if any response differs by a single byte. Currently 16 of 16 identical. A demo that quietly disagrees with the thing it demonstrates is worse than no demo.
189
+
190
+ ## Development
191
+
192
+ ```bash
193
+ git clone https://github.com/Siddhidesign/research-lens.git
194
+ cd research-lens && npm install && npm run build
195
+ npm run verify # parity between demo page and server
196
+ node docs/build.mjs # rebuild the self-contained demo page
197
+ ```
198
+
199
+ TypeScript, Node, `@modelcontextprotocol/sdk`, stdio transport. No runtime dependencies beyond the SDK.
200
+
201
+ ## Credits
202
+
203
+ Built by [Siddhi Manche](https://siddhidesign.github.io/Portfolio/), a UX researcher and designer, with an AI coding assistant.
204
+
205
+ The bundled sample is six sessions from an IRB-approved study (HUM00280873) on an AI personal finance product. Quotes are paraphrased and anonymised.
206
+
207
+ MIT licensed. Issues and pull requests welcome — particularly from researchers who try it on a real study and find where it falls short.