@originalvoices/mcp-server 1.0.3 → 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 OriginalVoices
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,7 +2,9 @@
 
 [![npm version](https://img.shields.io/npm/v/@originalvoices/mcp-server.svg)](https://www.npmjs.com/package/@originalvoices/mcp-server)
 
-An MCP (Model Context Protocol) server that provides access to [OriginalVoices](https://originalvoices.ai) AI twins for audience research.
+A local (stdio) MCP server for [OriginalVoices](https://originalvoices.ai): ask Digital Twins of real people from any MCP client.
+
+Most clients can connect to the hosted server at `https://api.originalvoices.ai/mcp` instead, with no install. See [Connect your assistant](https://docs.originalvoices.ai/connect).
 
 ## Installation
 
@@ -43,7 +45,7 @@ Add to your `claude_desktop_config.json`:
   "mcpServers": {
     "originalvoices": {
       "command": "node",
-      "args": ["/path/to/ov-mcp-server/dist/index.js"],
+      "args": ["/path/to/originalvoices-js/packages/mcp-server/dist/index.js"],
       "env": {
         "ORIGINALVOICES_API_KEY": "your-api-key"
       }
@@ -54,41 +56,42 @@ Add to your `claude_desktop_config.json`:
 
 ## Tools
 
-### ask_twins
+Same tools as the hosted server at `https://api.originalvoices.ai/mcp`, which is the recommended way to connect if your client supports HTTP.
 
-Ask questions to a specific audience using OriginalVoices AI twins.
+### ask_twins
 
-**Parameters:**
+Ask up to 15 questions to Digital Twins. Pass exactly one of `audience`, `audienceId` or `studyId`.
 
 | Name | Type | Description |
 |------|------|-------------|
-| `audience` | string | Description of the audience |
-| `questions` | string[] | Array of questions to ask the audience |
-
-**Example:**
+| `questions` | array, required | A string is an open question. `{ question, choices, multiple? }` is a choice question with 2-20 options. |
+| `audience` | string | Who to ask, in plain words |
+| `audienceId` | string | A saved audience from `list_audiences` |
+| `studyId` | string | A study from `list_studies`; its participants answer |
+| `filter` | string | Only with `studyId`: narrow participants in plain words |
+| `sampleSize` | integer | How many participants to ask |
 
 ```json
 {
   "audience": "UK, 18-30, fitness enthusiasts",
   "questions": [
-    "When purchasing running shoes, what's most important to you?",
-    "How often do you replace your running shoes?"
+    { "question": "Which matters most in a running shoe?", "choices": ["Price", "Comfort", "Style"] },
+    "Why did you pick that?"
   ]
 }
 ```
 
-## Development
+### list_audiences
 
-```bash
-# Install dependencies
-npm install
+Lists your saved audiences. Pass an `id` to `ask_twins` as `audienceId`.
 
-# Build
-npm run build
+### list_studies
 
-# Watch mode
-npm run dev
-```
+Lists your finished studies. Pass an `id` to `ask_twins` as `studyId`.
+
+## Development
+
+See the [repo README](../../README.md).
 
 ## FAQ
 

package/dist/index.js

@@ -2,104 +2,137 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import OriginalVoices from "originalvoices";
+import { OriginalVoices, OriginalVoicesError } from "originalvoices";
 const server = new McpServer({
     name: "originalvoices",
-    version: "1.0.3",
+    version: "2.0.0",
 });
-const client = new OriginalVoices({
-    apiKey: process.env.ORIGINALVOICES_API_KEY,
-});
-server.tool("ask_twins", "Ask questions to a specific audience using Original Voices AI twins. Use this for ad-hoc audience queries with a free-text audience description.", {
-    audience: z
-        .string()
-        .min(1)
-        .max(255)
-        .describe("The target audience to query. Typically includes demographics such as age range, gender, and location. Examples: 'Women aged 35-55 in the US and UK', 'Gen Z men (18-25) in urban areas'."),
-    questions: z
-        .array(z.string().min(1).max(2048))
-        .min(1)
-        .max(15)
-        .describe("The questions to ask the Digital Twins. Open-ended questions work best."),
-}, async ({ audience, questions }) => {
-    const response = await client.ask.open({
-        questions,
-        audiencePrompt: audience,
+// Created on first use, so a missing key shows up as a tool error rather than a crash.
+let client;
+const ov = () => (client ??= new OriginalVoices());
+// Same tools and descriptions as the hosted server at https://api.originalvoices.ai/mcp.
+const QuestionSchema = z.union([
+    z.string().min(1).max(2048),
+    z.object({
+        question: z.string().min(1).max(2048),
+        choices: z
+            .array(z.string().min(1).max(255))
+            .min(2)
+            .max(20)
+            .optional()
+            .describe("2-20 distinct options. Omit for an open question."),
+        multiple: z.boolean().optional().describe("Allow several picks. Defaults to false."),
+    }),
+]);
+/** MCP questions to POST /v1/ask questions, with ids q1, q2, … in order. */
+function toAskQuestions(questions) {
+    return questions.map((q, i) => {
+        const id = `q${i + 1}`;
+        if (typeof q === "string")
+            return { id, type: "open", question: q };
+        if (!q.choices)
+            return { id, type: "open", question: q.question };
+        return {
+            id,
+            type: "choice",
+            question: q.question,
+            choices: q.choices,
+            isMultipleChoice: q.multiple ?? false,
+        };
     });
+}
+function result(data) {
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}
+function errorResult(error) {
     return {
         content: [
             {
                 type: "text",
-                text: JSON.stringify(response.data, null, 2),
+                text: JSON.stringify({
+                    error: error instanceof OriginalVoicesError ? error.code : "error",
+                    message: error instanceof Error ? error.message : String(error),
+                }),
             },
         ],
+        isError: true,
     };
-});
-server.tool("ask_audience", "Ask questions to a previously saved audience by its ID. Use list_projects first to discover projects and their audiences.", {
+}
+server.tool("ask_twins", [
+    "Ask questions to Digital Twins and get each Twin's individual answers.",
+    "Each Digital Twin represents a real person: it is built from their data, experiences and opinions, and owned and trained by that person.",
+    "Pass exactly one of: audience (who to ask, described in words — the default), audienceId (a saved or network audience from list_audiences) or studyId (a study from list_studies; each participant's Digital Twin answers with that person's whole study conversation in context).",
+    "Questions can be open (a plain string, answered in the Twin's own words) or choice (an object with choices, returning the share of Twins that picked each option). Each Twin answers all questions in order in one conversation, so an open question after a choice question can ask why they picked it. Every answer carries a low, medium or high confidence.",
+    "Answers are billed per Twin answer (Twins × questions).",
+].join(" "), {
+    audience: z
+        .string()
+        .min(1)
+        .max(2048)
+        .optional()
+        .describe("The target audience to query, passed through exactly as the user describes it. Use this unless the user refers to a saved audience or a study. Typically includes demographics such as age range, gender, and location/country. Keep it separate from the questions: the audience describes WHO to ask, not WHAT they care about. Examples: 'Women aged 35-55 in the US and UK', 'Gen Z men (18-25) in urban areas'."),
     audienceId: z
         .string()
         .min(1)
-        .describe("The audience ID to query. Obtain IDs from list_projects."),
+        .max(256)
+        .optional()
+        .describe("A saved or network audience to ask, instead of audience. Obtain IDs from list_audiences: a UUID for a saved audience, or '{networkId}:{audienceSlug}' for a network audience."),
+    studyId: z
+        .string()
+        .uuid()
+        .optional()
+        .describe("A study id from list_studies, instead of audience: its participants answer."),
     questions: z
-        .array(z.string().min(1).max(2048))
+        .array(QuestionSchema)
         .min(1)
         .max(15)
-        .describe("The questions to ask the Digital Twins. Open-ended questions work best."),
-}, async ({ audienceId, questions }) => {
-    const response = await client.ask.open({
-        questions,
-        audienceId,
-    });
-    return {
-        content: [
-            {
-                type: "text",
-                text: JSON.stringify(response.data, null, 2),
-            },
-        ],
-    };
-});
-server.tool("ask_project", "Ask questions to a filtered subset of a project's survey panel. Filters respondents by demographics and survey answers using natural language. Use list_projects first to see available projects.", {
-    projectId: z
-        .string()
-        .min(1)
-        .describe("The project ID to query. Obtain IDs from list_projects."),
+        .describe("The questions to ask, 1-15, in order. An open question is a plain string. A choice question is an object { question, choices: 2-20 distinct options, multiple?: true to allow several picks }. Open questions work best for qualitative insights; use choice questions for numbers, shares or a preference between options."),
     filter: z
         .string()
         .min(1)
         .max(1024)
         .optional()
-        .describe("Optional natural language filter to select respondents. If omitted, all respondents are queried. Examples: 'Samsung users', 'women over 30 who worry about battery'."),
-    questions: z
-        .array(z.string().min(1).max(2048))
+        .describe("Only with studyId. Free-text criteria matched against each participant's profile and what they said in the study, e.g. 'said price was the main barrier'. Omit to ask everyone."),
+    sampleSize: z
+        .number()
+        .int()
         .min(1)
-        .max(15)
-        .describe("The questions to ask the Digital Twins. Open-ended questions work best."),
-}, async ({ projectId, filter, questions }) => {
-    const response = await client.ask.project(projectId, {
-        questions,
-        filter,
-    });
-    return {
-        content: [
-            {
-                type: "text",
-                text: JSON.stringify(response.data, null, 2),
-            },
-        ],
-    };
+        .max(200)
+        .optional()
+        .describe("How many participants to ask. Defaults: described audiences 25; saved audiences everyone up to 100; interview studies everyone; twin-survey studies 25. Audiences take at most 100."),
+}, async ({ audience, audienceId, studyId, questions, filter, sampleSize }) => {
+    try {
+        return result(await ov().ask({
+            target: { audience, audienceId, studyId },
+            questions: toAskQuestions(questions),
+            filter,
+            sampleSize,
+        }));
+    }
+    catch (error) {
+        return errorResult(error);
+    }
 });
-server.tool("list_projects", "List all research projects in the user's organization. Each project contains survey questions and pre-defined audiences. Use this to discover projects before using ask_project or ask_audience.", {}, async () => {
-    // SDK projects.list() has a bug (hits /v1/audiences), so use client.get directly
-    const response = await client.get("/v1/projects");
-    return {
-        content: [
-            {
-                type: "text",
-                text: JSON.stringify(response.data, null, 2),
-            },
-        ],
-    };
+server.tool("list_audiences", "List the saved audiences in the user's organization. Pass an entry's `id` to ask_twins as audienceId.", {}, async () => {
+    try {
+        return result(await ov().audiences.list());
+    }
+    catch (error) {
+        return errorResult(error);
+    }
+});
+server.tool("list_studies", [
+    "List the organization's finished studies.",
+    "kind HUMAN_INTERVIEW: real people interviewed one-to-one by an AI moderator.",
+    "kind TWIN_SURVEY: a questionnaire answered by Digital Twins.",
+    "Each entry has the participant count and the study's questions. Pass the returned `id` to ask_twins as studyId.",
+].join(" "), {}, async () => {
+    try {
+        return result(await ov().studies.list());
+    }
+    catch (error) {
+        return errorResult(error);
+    }
 });
 async function main() {
     const transport = new StdioServerTransport();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@originalvoices/mcp-server",
-  "version": "1.0.3",
+  "version": "2.0.0",
   "mcpName": "io.github.ovlabs/originalvoices",
   "description": "MCP server for OriginalVoices - Ask AI twins questions about any audience",
   "main": "dist/index.js",
@@ -12,7 +12,8 @@
     "build": "tsc",
     "start": "node dist/index.js",
     "dev": "tsc --watch",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "typecheck": "tsc --noEmit"
   },
   "keywords": [
     "mcp",
@@ -26,7 +27,8 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/ovlabs/mcp-server-originalvoices.git"
+    "url": "git+https://github.com/ovlabs/originalvoices-js.git",
+    "directory": "packages/mcp-server"
   },
   "engines": {
     "node": ">=20"
@@ -37,7 +39,7 @@
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.25.2",
-    "originalvoices": "^0.14.1",
+    "originalvoices": "^1.0.0",
     "zod": "^4.3.5"
   },
   "devDependencies": {