@thesapientcompany/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Sapient Company
+
+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

@@ -0,0 +1,83 @@
+# @thesapientcompany/mcp
+
+MCP (Model Context Protocol) server for the **Sapient** brain-response API. It lets any MCP client — Claude Code, Claude Desktop, Cursor, etc. — submit content to Sapient, read scan results, query your cross-scan intelligence, and read the Sapient knowledge base.
+
+Sapient predicts how a real human brain would respond to a piece of content (video, audio, image, or text) — second by second — and distills that into a score, a grade, and seven lenses.
+
+## Install
+
+Add it to Claude Code with one command:
+
+```bash
+claude mcp add sapient --env SAPIENT_API_KEY=sk_live_… -- npx -y @thesapientcompany/mcp
+```
+
+Or run the binary directly:
+
+```bash
+SAPIENT_API_KEY=sk_live_… npx -y @thesapientcompany/mcp
+```
+
+### Claude Desktop / generic MCP config
+
+```json
+{
+  "mcpServers": {
+    "sapient": {
+      "command": "npx",
+      "args": ["-y", "@thesapientcompany/mcp"],
+      "env": { "SAPIENT_API_KEY": "sk_live_…" }
+    }
+  }
+}
+```
+
+### Remote / HTTP note
+
+This package is a **stdio** server (it runs locally and talks to the hosted Sapient API at `https://www.thesapientcompany.com`). A hosted, remote MCP endpoint over Streamable HTTP is on the roadmap; until then, run this stdio server locally with your `sk_live_` key. You can point it at a different API host with `SAPIENT_BASE_URL`.
+
+## Configuration
+
+| Env var | Required | Description |
+| --- | --- | --- |
+| `SAPIENT_API_KEY` | yes | Your `sk_live_…` key (Settings → API at thesapientcompany.com). |
+| `SAPIENT_BASE_URL` | no | Override the API base URL (default `https://www.thesapientcompany.com`). |
+
+## Tools
+
+| Tool | What it does |
+| --- | --- |
+| `run_scan` | Submit content (`url` **or** `text`); pick `lenses` / `options`; set `wait: true` to poll to completion and return the full result. |
+| `get_scan` | Fetch one scan by `scan_id` — `{ status }` while running, the rich result (timeline, moments, summary) when complete. |
+| `list_lenses` | The 7 selectable lenses with one-line descriptions. |
+| `my_history` | Your scan history (`GET /v1/scans`). |
+| `my_intelligence` | Your cross-scan patterns + semantic recall (`GET /v1/intelligence?q=`). |
+
+### The 7 lenses
+
+`attention`, `purchase_intent`, `manipulation`, `emotion`, `cognitive_effort`, `memory`, `surprise`. The default top-3 (when you don't choose) are **attention, purchase_intent, manipulation**.
+
+## Resources
+
+| URI | What it is |
+| --- | --- |
+| `sapient://knowledge-base` | Full-text explanation of how the Sapient model works — the pipeline, the 7 networks, the lenses, and how to read a scan. |
+
+## Errors
+
+- **401** → `SAPIENT_API_KEY` is missing/invalid — set a valid `sk_live_` key.
+- **402** → out of credits — add API credits in Settings → API.
+- **403** → a paid plan is required to use the API.
+- **404** → no such scan, or it isn't yours.
+- **429** → rate limited; retry with backoff.
+
+## Build from source
+
+```bash
+npm install
+npm run build   # tsc → dist/
+```
+
+## License
+
+MIT

package/dist/client.js

@@ -0,0 +1,165 @@
+/**
+ * Thin typed client for the Sapient API (v1). Uses global fetch (Node >= 18).
+ *
+ * Base URL defaults to https://www.thesapientcompany.com and may be overridden
+ * with SAPIENT_BASE_URL. Auth is a Bearer `sk_live_…` key from SAPIENT_API_KEY.
+ *
+ * Endpoints:
+ *   POST /v1/scans            submit a scan      -> { scan_id, status, lenses }
+ *   GET  /v1/scans/{id}       poll one scan      -> rich shape when complete
+ *   GET  /v1/scans            caller's history   -> { object, total, scans, ... }
+ *   GET  /v1/intelligence?q=  cross-scan rollup  -> { scan_count, ... , recall? }
+ */
+export const DEFAULT_BASE_URL = 'https://www.thesapientcompany.com';
+/** The 7 selectable lenses, with one-line descriptions. */
+export const LENSES = [
+    { key: 'attention', description: 'How much the content holds focus, second by second.' },
+    { key: 'purchase_intent', description: 'Approach-vs-avoid buy signal — desire to act.' },
+    { key: 'manipulation', description: 'Emotional pull vs. reasoning — how much it pushes vs. persuades.' },
+    { key: 'emotion', description: 'Emotional valence and intensity of the response.' },
+    { key: 'cognitive_effort', description: 'How hard the brain is working to process the content.' },
+    { key: 'memory', description: 'How likely the content is to stick and be recalled later.' },
+    { key: 'surprise', description: 'Involuntary salience — how much something grabs attention.' },
+];
+export const LENS_KEYS = LENSES.map((l) => l.key);
+export const DEFAULT_LENSES = ['attention', 'purchase_intent', 'manipulation'];
+export class SapientApiError extends Error {
+    status;
+    code;
+    constructor(status, message, code) {
+        super(message);
+        this.name = 'SapientApiError';
+        this.status = status;
+        this.code = code;
+    }
+}
+/** Map an HTTP error into a clear, actionable message. */
+function explain(status, bodyMsg, bodyCode) {
+    switch (status) {
+        case 401:
+            return 'Unauthorized (401): set SAPIENT_API_KEY to a valid sk_live_ key.';
+        case 402:
+            return 'Insufficient balance (402): add API credits in Settings → API at thesapientcompany.com.';
+        case 403:
+            return `Plan required (403): ${bodyMsg || 'upgrade to a paid plan to use the API.'}`;
+        case 404:
+            return 'Not found (404): no such scan, or it does not belong to your org.';
+        case 429:
+            return 'Rate limited (429): retry with backoff.';
+        default:
+            return bodyMsg
+                ? `Sapient API error (${status}${bodyCode ? ` ${bodyCode}` : ''}): ${bodyMsg}`
+                : `Sapient API error (${status}).`;
+    }
+}
+export class SapientClient {
+    apiKey;
+    baseUrl;
+    constructor(opts) {
+        this.apiKey = (opts?.apiKey ?? process.env.SAPIENT_API_KEY ?? '').trim();
+        this.baseUrl = (opts?.baseUrl ?? process.env.SAPIENT_BASE_URL ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+    }
+    hasKey() {
+        return Boolean(this.apiKey);
+    }
+    requireKey() {
+        if (!this.apiKey) {
+            throw new SapientApiError(401, 'Unauthorized (401): set SAPIENT_API_KEY to a valid sk_live_ key.', 'unauthorized');
+        }
+    }
+    async request(method, path, body) {
+        this.requireKey();
+        const url = `${this.baseUrl}${path}`;
+        let res;
+        try {
+            res = await fetch(url, {
+                method,
+                headers: {
+                    Authorization: `Bearer ${this.apiKey}`,
+                    'Content-Type': 'application/json',
+                    Accept: 'application/json',
+                },
+                body: body != null ? JSON.stringify(body) : undefined,
+            });
+        }
+        catch (e) {
+            throw new SapientApiError(0, `Network error calling ${url}: ${e?.message || e}`);
+        }
+        const text = await res.text();
+        let json = null;
+        try {
+            json = text ? JSON.parse(text) : null;
+        }
+        catch {
+            /* non-JSON body */
+        }
+        if (!res.ok) {
+            throw new SapientApiError(res.status, explain(res.status, json?.message, json?.error), json?.error);
+        }
+        return json ?? {};
+    }
+    /** POST /v1/scans — submit. Returns { scan_id, status, lenses }. */
+    async submitScan(input) {
+        const hasUrl = typeof input.url === 'string' && input.url.trim();
+        const hasText = typeof input.text === 'string' && input.text.trim();
+        if (!hasUrl && !hasText) {
+            throw new SapientApiError(400, 'Provide either a url or text to scan.', 'bad_request');
+        }
+        const inputObj = hasUrl
+            ? { type: 'url', url: input.url.trim(), ...(input.modality ? { modality: input.modality } : {}) }
+            : { type: 'text', text: input.text.trim() };
+        const payload = { input: inputObj };
+        if (input.lenses && input.lenses.length)
+            payload.lenses = input.lenses;
+        if (input.options)
+            payload.options = input.options;
+        if (input.webhook_url)
+            payload.webhook_url = input.webhook_url;
+        return this.request('POST', '/v1/scans', payload);
+    }
+    /** GET /v1/scans/{id}. While in-flight: { scan_id, status }. Complete: rich shape. */
+    async getScan(scanId) {
+        return this.request('GET', `/v1/scans/${encodeURIComponent(scanId)}`);
+    }
+    /** GET /v1/scans — caller's history. */
+    async listScans(opts) {
+        const qs = new URLSearchParams();
+        if (opts?.limit != null)
+            qs.set('limit', String(opts.limit));
+        if (opts?.offset != null)
+            qs.set('offset', String(opts.offset));
+        const suffix = qs.toString() ? `?${qs}` : '';
+        return this.request('GET', `/v1/scans${suffix}`);
+    }
+    /** GET /v1/intelligence?q= — cross-scan rollup + optional semantic recall. */
+    async intelligence(q) {
+        const suffix = q && q.trim() ? `?q=${encodeURIComponent(q.trim())}` : '';
+        return this.request('GET', `/v1/intelligence${suffix}`);
+    }
+    /**
+     * Submit then poll GET /v1/scans/{id} until status is terminal.
+     * Returns the final scan object. Throws on timeout.
+     */
+    async runScanToCompletion(input, opts) {
+        const submitted = await this.submitScan(input);
+        const intervalMs = opts?.intervalMs ?? 5000;
+        const timeoutMs = opts?.timeoutMs ?? 5 * 60 * 1000;
+        const started = Date.now();
+        // Small initial delay so the run can register.
+        await sleep(Math.min(intervalMs, 2000));
+        while (true) {
+            const scan = await this.getScan(submitted.scan_id);
+            const status = scan?.status;
+            opts?.onTick?.(status);
+            if (status === 'complete' || status === 'error' || status === 'cancelled')
+                return scan;
+            if (Date.now() - started > timeoutMs) {
+                throw new SapientApiError(0, `Timed out after ${Math.round(timeoutMs / 1000)}s waiting for scan ${submitted.scan_id} (last status: ${status}). It is still running — poll get_scan later.`);
+            }
+            await sleep(intervalMs);
+        }
+    }
+}
+export function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}

package/dist/index.js

@@ -0,0 +1,215 @@
+#!/usr/bin/env node
+/**
+ * Sapient MCP server (stdio).
+ *
+ * Exposes the Sapient brain-response API to any MCP client (Claude Desktop,
+ * Claude Code, etc.) as tools + a knowledge-base resource.
+ *
+ * Tools:
+ *   run_scan         submit content (url or text); optionally poll to completion
+ *   get_scan         poll one scan by id
+ *   list_lenses      the 7 selectable lenses + one-line descriptions
+ *   my_history       GET /v1/scans  (caller's scan history)
+ *   my_intelligence  GET /v1/intelligence?q=  (cross-scan patterns + recall)
+ *
+ * Resources:
+ *   sapient://knowledge-base   the full Sapient knowledge base (how the model works)
+ *
+ * Config (env):
+ *   SAPIENT_API_KEY    required  — an sk_live_ key
+ *   SAPIENT_BASE_URL   optional  — override the API base URL
+ */
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { SapientClient, SapientApiError, LENSES, LENS_KEYS } from './client.js';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/** Load the bundled knowledge base (shipped next to dist/). */
+function loadKnowledgeBase() {
+    const candidates = [
+        join(__dirname, '..', 'knowledge-base.txt'),
+        join(__dirname, 'knowledge-base.txt'),
+    ];
+    for (const p of candidates) {
+        try {
+            return readFileSync(p, 'utf8');
+        }
+        catch {
+            /* try next */
+        }
+    }
+    return 'Sapient knowledge base not bundled. See https://docs.thesapientcompany.com';
+}
+const KNOWLEDGE_BASE = loadKnowledgeBase();
+const client = new SapientClient();
+const server = new McpServer({ name: 'sapient', version: '0.1.0' });
+// ── helpers ──────────────────────────────────────────────────────────────────
+function ok(text) {
+    return { content: [{ type: 'text', text }] };
+}
+function fail(text) {
+    return { content: [{ type: 'text', text }], isError: true };
+}
+function errText(e) {
+    if (e instanceof SapientApiError)
+        return e.message;
+    return `Unexpected error: ${e?.message || String(e)}`;
+}
+function json(value) {
+    return JSON.stringify(value, null, 2);
+}
+// ── Resource: knowledge base ─────────────────────────────────────────────────
+server.registerResource('knowledge-base', 'sapient://knowledge-base', {
+    title: 'Sapient knowledge base',
+    description: 'Full-text explanation of how the Sapient brain-response model works: the pipeline, the 7 networks, the lenses, and how to read a scan.',
+    mimeType: 'text/plain',
+}, async (uri) => ({
+    contents: [{ uri: uri.href, mimeType: 'text/plain', text: KNOWLEDGE_BASE }],
+}));
+// ── Tool: list_lenses ────────────────────────────────────────────────────────
+server.registerTool('list_lenses', {
+    title: 'List lenses',
+    description: 'List the 7 selectable Sapient lenses with one-line descriptions. Default top-3 when none are picked: attention, purchase_intent, manipulation.',
+    inputSchema: {},
+}, async () => {
+    const lines = LENSES.map((l) => `- ${l.key}: ${l.description}`).join('\n');
+    return ok(`Sapient lenses (default top-3 = attention, purchase_intent, manipulation):\n\n${lines}`);
+});
+// ── Tool: run_scan ───────────────────────────────────────────────────────────
+server.registerTool('run_scan', {
+    title: 'Run a scan',
+    description: "Submit content to Sapient and get a brain-response scan. Provide exactly one of `url` (a public video/audio/image URL) or `text`. Optionally choose `lenses` (any of the 7; default top-3) and `options`. Set `wait: true` to poll until the scan completes and return the full result; otherwise returns { scan_id, status } for you to poll later with get_scan.",
+    inputSchema: {
+        url: z
+            .string()
+            .url()
+            .optional()
+            .describe('Public asset URL (video, audio, or image). Provide this OR text.'),
+        text: z.string().optional().describe('Raw copy to analyze. Provide this OR url.'),
+        modality: z
+            .enum(['video', 'audio', 'image'])
+            .optional()
+            .describe('Optional hint when url is supplied (default video).'),
+        lenses: z
+            .array(z.enum(LENS_KEYS))
+            .optional()
+            .describe('Lenses to compute. Default top-3: attention, purchase_intent, manipulation.'),
+        options: z
+            .object({
+            include_reasons: z.boolean().optional(),
+            include_raw: z.boolean().optional(),
+            include_fmri: z.boolean().optional(),
+            include_benchmark: z.boolean().optional(),
+        })
+            .optional()
+            .describe('Toggle reasons / raw networks / fMRI url / benchmark percentiles.'),
+        webhook_url: z
+            .string()
+            .url()
+            .optional()
+            .describe('Optional http(s) URL to receive a POST when the scan completes.'),
+        wait: z
+            .boolean()
+            .optional()
+            .describe('Poll until the scan completes (or fails) and return the full result.'),
+        timeout_sec: z
+            .number()
+            .int()
+            .positive()
+            .max(600)
+            .optional()
+            .describe('Max seconds to wait when wait=true (default 300).'),
+    },
+}, async (args) => {
+    try {
+        const input = {
+            url: args.url,
+            text: args.text,
+            modality: args.modality,
+            lenses: args.lenses,
+            options: args.options,
+            webhook_url: args.webhook_url,
+        };
+        if (args.wait) {
+            const scan = await client.runScanToCompletion(input, {
+                timeoutMs: (args.timeout_sec ?? 300) * 1000,
+            });
+            if (scan?.status !== 'complete') {
+                return fail(`Scan ${scan?.scan_id ?? ''} ended with status "${scan?.status}".\n\n${json(scan)}`);
+            }
+            return ok(`Scan complete.\n\n${json(scan)}`);
+        }
+        const submitted = await client.submitScan(input);
+        return ok(`Scan submitted (status: ${submitted.status}). Poll get_scan with scan_id="${submitted.scan_id}".\n\n${json(submitted)}`);
+    }
+    catch (e) {
+        return fail(errText(e));
+    }
+});
+// ── Tool: get_scan ───────────────────────────────────────────────────────────
+server.registerTool('get_scan', {
+    title: 'Get a scan',
+    description: 'Fetch one scan by id. While in-flight returns { scan_id, status }; when complete returns the rich result (timeline, moments, summary, optional raw/benchmark/fmri_url).',
+    inputSchema: {
+        scan_id: z.string().describe('The scan id returned by run_scan.'),
+    },
+}, async ({ scan_id }) => {
+    try {
+        const scan = await client.getScan(scan_id);
+        return ok(json(scan));
+    }
+    catch (e) {
+        return fail(errText(e));
+    }
+});
+// ── Tool: my_history ─────────────────────────────────────────────────────────
+server.registerTool('my_history', {
+    title: 'My scan history',
+    description: "List the caller's scan history (most recent first).",
+    inputSchema: {
+        limit: z.number().int().positive().max(100).optional().describe('How many to return (1–100, default 25).'),
+        offset: z.number().int().min(0).optional().describe('Pagination offset.'),
+    },
+}, async ({ limit, offset }) => {
+    try {
+        const data = await client.listScans({ limit, offset });
+        return ok(json(data));
+    }
+    catch (e) {
+        return fail(errText(e));
+    }
+});
+// ── Tool: my_intelligence ────────────────────────────────────────────────────
+server.registerTool('my_intelligence', {
+    title: 'My cross-scan intelligence',
+    description: "The caller's long-term, cross-scan brain intelligence: lens averages, average per-second curves, recurring weak spots, and (when q is given) semantic recall across past scans.",
+    inputSchema: {
+        q: z.string().optional().describe('Optional semantic query to recall matching moments across past scans.'),
+    },
+}, async ({ q }) => {
+    try {
+        const data = await client.intelligence(q);
+        return ok(json(data));
+    }
+    catch (e) {
+        return fail(errText(e));
+    }
+});
+// ── boot ─────────────────────────────────────────────────────────────────────
+async function main() {
+    if (!client.hasKey()) {
+        // Don't crash — the handshake should still work so a client can list tools.
+        // Tool calls will return a clear 401 message. Surface a hint on stderr.
+        process.stderr.write('[sapient-mcp] Warning: SAPIENT_API_KEY is not set. Tool calls will fail with 401 until you set it.\n');
+    }
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    process.stderr.write('[sapient-mcp] Sapient MCP server running on stdio.\n');
+}
+main().catch((e) => {
+    process.stderr.write(`[sapient-mcp] Fatal: ${e?.message || e}\n`);
+    process.exit(1);
+});

package/knowledge-base.txt

@@ -0,0 +1,245 @@
+# Sapient — Knowledge Base (full text)
+
+> The brain-response API. Submit content (video, audio, image, or text); Sapient predicts how a real human brain would respond, second by second, then distills that into a score, a grade, and seven lenses. The predicted brain response is the ground truth; the lenses, scores, and grades are plain-language explanations built on top of it.
+
+================================================================
+# How Sapient works
+
+Sapient is trained on real human fMRI brain responses. When you submit a piece of content, the model predicts how a human brain would respond to it — second by second — and distills that into a single, comparable read.
+
+## Brain is the ground truth, AI is the explanation
+
+The core idea is simple. The brain response is the measurement — the model predicts the actual pattern of activity a human brain would produce while watching, hearing, or reading your content. Everything above that is interpretation built on top of the measurement.
+
+- The brain response is the ground truth: a predicted activation across the whole cortex, every second.
+- The lenses, scores, and grades are supplementary — they translate that response into language a marketer or creator can act on.
+
+So when a scan says "attention drops at second 6," that isn't a guess from a language model reading your script. It's a reduction of a predicted brain signal into a plain word.
+
+## What a scan measures
+
+Every scan produces:
+
+- A headline score (0–100) — overall predicted engagement.
+- A letter grade (A–F) — the same signal, at a glance.
+- Seven lenses — interpretive cuts of the response (attention, purchase intent, manipulation, emotion, cognitive effort, memory, surprise).
+- The raw brain output — per-network activations and per-second time series, for teams that want to go deeper.
+
+## How to think about it
+
+A Sapient score is a directional prediction, not a guarantee. Use it to compare versions of the same idea (A vs B), to find the moment a piece loses attention, or to sanity-check creative before you spend. It is most powerful when you scan often and compare.
+
+================================================================
+# How the model works
+
+A scan moves through a fixed pipeline. Content goes in, a predicted brain response comes out, and that response is reduced step by step into something you can read at a glance. Each step is a faithful summary of the one before it — nothing is invented along the way.
+
+1. Content comes in. You submit a piece of content: a video, an audio clip, an image, or text. This is the raw material the model will respond to.
+2. Content becomes features. The content is turned into machine-readable features — what's being said, heard, and seen over time. Speech is transcribed, sound is characterized, and motion and imagery are tracked frame by frame. These features are the model's senses.
+3. The model predicts a brain response. From those features, the model predicts a full brain response: activity across roughly 20,000 points on the cortex, for every moment of the content. This is the ground-truth measurement everything else is built on.
+4. The brain is reduced to 7 networks per second. The cortex-wide response is summarized into 7 well-established brain networks, one value each, every second. Each network corresponds to a plain-English function — seeing, moving, focusing, alerting, feeling, reasoning, reflecting.
+5. Networks blend into KPIs. The seven per-second networks are blended into 10 KPIs per second — intermediate measures that combine networks into more specific signals.
+6. KPIs roll up into composites. The KPIs are grouped into 5 composites — higher-level summaries of how the content is performing.
+7. Everything resolves into lenses and a score. Finally, the response resolves into the 7 lenses — attention, purchase intent, manipulation, emotion, cognitive effort, memory, and surprise — plus an overall score and grade. These are the human-readable answers.
+
+## Why the reduction matters
+
+Each layer is a lossy but honest summary of the one beneath it. The deepest layer — the predicted brain response — is the most precise and the least readable. The shallowest layer — the score — is the easiest to act on and the least detailed. You choose how deep to go depending on the question you're asking.
+
+================================================================
+# The 7 networks
+
+The brain doesn't work as one undivided whole. Decades of fMRI research describe the cortex as a set of large-scale networks, each handling a broad kind of work. Sapient summarizes its predicted brain response into seven of these networks, one value each, every second. Reading the networks is the most direct way to understand why a lens moved. Every lens is a blend of these seven signals.
+
+The seven networks:
+
+- Visual — Seeing & imagery. How much the content is engaging the eyes — visual detail, motion, and mental imagery.
+- Somatomotor — Body & movement / voice & sound. Response to physical action, gesture, and the texture of voice and sound.
+- Dorsal Attention — Focused attention. How hard the viewer is deliberately concentrating — the focus network.
+- Ventral Attention — Salience & surprise. How much something is grabbing attention involuntarily — the alerting network.
+- Limbic — Emotion & reward. Emotional pull and the sense of reward or desire.
+- Frontoparietal — Reasoning & effort. Active thinking, problem-solving, and mental work.
+- Default Mode — Reflection, memory & self-relevance. Inward processing — relating content to yourself, your memories, and meaning.
+
+How to read them:
+
+- Visual rises with rich, moving, or detailed imagery; it falls on static or empty frames.
+- Somatomotor lifts with physical action, gesture, and the grain of a voice or a sound.
+- Dorsal Attention is voluntary focus — the viewer choosing to lock in.
+- Ventral Attention is involuntary capture — a cut, a noise, or a twist yanking attention without permission.
+- Limbic is the heart of emotional and reward responses; it's the engine behind both feeling and wanting.
+- Frontoparietal rises when the viewer has to work — to follow, decode, or reason through something.
+- Default Mode rises when content turns inward — memory, self-relevance, reflection, meaning.
+
+================================================================
+# From networks to lenses
+
+The seven networks are the raw signal. The seven lenses are the answers. Each lens is a question, and each question is best answered by a particular blend of networks. The model reads the second-by-second networks and resolves them into a single 0–100 read per lens — and tracks how that read rises and falls across the content. No language model is guessing here. The lens is a reduction of the predicted brain response, not an opinion about your script.
+
+Which networks drive which lens:
+
+- Attention — reads most from Dorsal Attention and Ventral Attention. Question: Is the viewer locked in?
+- Purchase Intent — reads most from Limbic (reward). Question: Will they want it?
+- Manipulation — reads most from Limbic and Ventral Attention versus Frontoparietal. Question: Is it pressuring more than persuading?
+- Emotion — reads most from Limbic. Question: How emotionally charged is this moment?
+- Cognitive Effort — reads most from Frontoparietal. Question: How much mental work is this taking?
+- Memory — reads most from Default Mode. Question: Will this be remembered and absorbed?
+- Surprise — reads most from Ventral Attention. Question: Was that unexpected?
+
+Why this is the "why": Because every lens traces back to specific networks, you can always ask why a number is what it is. A high Attention read with a low Memory read means the focus networks are firing but the reflection network isn't — the content grabs but doesn't stick. A high Manipulation read means emotional and salience networks are doing the heavy lifting while the reasoning network stays quiet. The lenses are deliberately overlapping cuts of one underlying response — it lets you see the same moment from seven angles at once.
+
+================================================================
+# The 7 lenses (overview)
+
+A scan returns seven lenses. Each is a 0–100 read on one dimension of how a brain responds to your content — and each traces back to specific brain networks, so every number has a why.
+
+- Attention — Whether the viewer is locked in, and where focus slips.
+- Purchase Intent — Reward and desire; whether they'll want it.
+- Manipulation — Persuasive or coercive load; pressure vs. reasoning.
+- Emotion — Emotional salience; how much the content makes you feel.
+- Cognitive Effort — Mental work; how hard the content is to process.
+- Memory — Whether the content will be remembered and absorbed.
+- Surprise — Novelty; how unexpected a moment is.
+
+Choosing a lens:
+
+- For ads and creative, start with Attention and Purchase Intent.
+- For brand and narrative, lean on Emotion and Memory.
+- For explainers and education, watch Cognitive Effort and Memory.
+- Use Manipulation as a guardrail, and Surprise to find the hook and the twists.
+
+================================================================
+# Lens: Attention
+
+The Attention lens analyzes for whether the viewer is locked in. It reads both kinds of focus: the deliberate concentration of someone choosing to pay attention, and the involuntary pull of something that grabs them whether they meant to look or not. Tracked second by second, it shows exactly where a piece holds and where it lets go.
+
+What it analyzes for: sustained focus across the timeline; the moment attention drops off; whether the opening earns the first few seconds.
+
+When to use it:
+- Finding the drop-off in a video ad — spot the exact second viewers disengage.
+- Testing a hook — compare the first three seconds of two openings; the one that holds Attention earlier wins the scroll.
+- Pacing a long-form edit — find slow stretches that need trimming before the viewer drifts.
+
+Reading the score:
+- High — the content is holding focus. Viewers are locked in and staying with it.
+- Low — focus is slipping. The content isn't earning continued attention, and viewers are likely to scroll or tune out.
+
+================================================================
+# Lens: Purchase Intent
+
+The Purchase Intent lens analyzes for desire. It reads the brain's reward response — the pull toward wanting, approaching, and acquiring. Where Attention tells you whether someone is watching, Purchase Intent tells you whether watching is turning into wanting.
+
+What it analyzes for: reward and desire as the content unfolds; whether a product reveal lands as appealing; the moment interest tips into intent.
+
+When to use it:
+- Timing the product reveal — see whether desire peaks when the product appears.
+- Comparing two offers — read which one drives a stronger reward response.
+- Choosing a thumbnail or hero shot — pick the frame with the highest Purchase Intent read.
+
+Reading the score:
+- High — the content is generating real desire. The reward response is firing.
+- Low — the content isn't creating pull. It may inform or entertain, but it isn't making anyone want the thing.
+
+================================================================
+# Lens: Manipulation
+
+The Manipulation lens analyzes for persuasive and coercive load. It reads how much the content is leaning on emotional pressure and involuntary triggers versus reasoning and genuine appeal. It's best used as a guardrail — a check on how a piece is winning people, not just whether it's working.
+
+What it analyzes for: emotional pressure and urgency tactics; coercive load — pushing rather than convincing; the balance between feeling and reasoning.
+
+When to use it:
+- Brand-safety review — make sure persuasion isn't tipping into pressure that could damage trust.
+- Diagnosing a high-converting but risky ad — see whether the desire is earned or pressured.
+- Comparing a hard sell vs. a soft sell — see how much each leans on coercive load.
+
+Reading the score:
+- High — the content is leaning hard on emotional pressure and involuntary triggers rather than reasoning. A flag worth a second look.
+- Low — the content is persuading through genuine appeal and reasoning, with little coercive load.
+
+================================================================
+# Lens: Emotion
+
+The Emotion lens analyzes for emotional salience — how much the content moves the viewer. It reads the brain's emotional response and tracks where feeling rises and falls across the timeline.
+
+What it analyzes for: the strength of the emotional response; the moment a piece lands or falls flat; whether the emotional beat arrives where you intended.
+
+When to use it:
+- Placing the emotional peak in a brand film — confirm the climactic beat produces the strongest response.
+- Testing music or voiceover — read which soundtrack raises emotional salience more.
+- Checking a story that should move people — if Emotion stays flat, the story isn't landing.
+
+Reading the score:
+- High — the content is emotionally charged. It's producing a strong feeling response.
+- Low — the content is emotionally flat. It may be clear, but it isn't moving anyone.
+
+================================================================
+# Lens: Cognitive Effort
+
+The Cognitive Effort lens analyzes for mental work. It reads how hard the viewer's brain is working to follow, decode, and reason through the content. Some effort is good — it means the viewer is engaged. Too much means the content is hard to follow and people give up.
+
+What it analyzes for: how much active thinking the content demands; the point where a piece becomes too hard to follow; whether an explanation is clear or overloaded.
+
+When to use it:
+- Simplifying an explainer — find the moment effort spikes, where the message gets too dense.
+- Pacing a complex pitch — if effort stays high throughout, spread the load or cut the complexity.
+- Checking a deliberately challenging piece — confirm effort rises enough to signal engagement without tipping into confusion.
+
+Reading the score:
+- High — the content demands a lot of mental work. A risk of losing people if it stays high.
+- Low — the content is easy to process. Effortless to follow, though it may not be challenging anyone.
+
+================================================================
+# Lens: Memory
+
+The Memory lens analyzes for whether the content will stick. It reads the brain's inward, reflective processing — the activity tied to relating content to yourself, your memories, and meaning. Attention gets people watching; Memory tells you whether anything stays with them afterward.
+
+What it analyzes for: how likely the content is to be encoded and remembered; whether a message is being absorbed or just passing through; the moments most likely to stay with the viewer.
+
+When to use it:
+- Checking whether a brand moment lands — read Memory at the logo or tagline reveal.
+- Diagnosing high attention, low recall — a piece that holds Attention but scores low on Memory grabs focus without sticking.
+- Comparing two ways to deliver a key message — pick the one that drives a stronger Memory read.
+
+Reading the score:
+- High — the content is being absorbed. Likely to be encoded and remembered.
+- Low — the content is passing through. People may watch it, but little is staying with them.
+
+================================================================
+# Lens: Surprise
+
+The Surprise lens analyzes for novelty. It reads the brain's alerting response — the involuntary spike that fires when something unexpected happens. Surprise is what makes a hook stop the scroll and a twist re-capture attention.
+
+What it analyzes for: how unexpected each moment is; whether a hook genuinely breaks the pattern; the twists and turns that re-capture attention.
+
+When to use it:
+- Testing whether a hook surprises — a strong hook produces a clear spike in the opening seconds.
+- Placing a twist or reveal — confirm the reveal lands as unexpected and isn't telegraphed too early.
+- Refreshing a tired format — if Surprise stays flat, the content is too predictable.
+
+Reading the score:
+- High — the content is breaking expectations. Something unexpected is pulling attention in.
+- Low — the content is predictable. It follows the pattern the viewer expected.
+
+================================================================
+# Data layers
+
+A scan can answer at different depths. The same response can be returned as a precise, cortex-wide brain signal — or as a single sentence. The layers run from deepest (most precise, least readable) to simplest (most readable, least detailed).
+
+- Per-vertex fMRI (deepest) — the full predicted brain response, activity across roughly 20,000 points on the cortex, for every moment. The ground truth. Use it for research, custom modeling, or the unreduced signal.
+- Per-second networks — the response summarized into the 7 brain networks, one value each, every second. Use it to understand why the content performs the way it does.
+- Per-second lens scores — the 7 lenses tracked second by second. Use it to see how each lens moves across the timeline.
+- Moments — the notable peaks and drops. Use it to find the exact moments worth keeping or cutting.
+- Summary (simplest) — overall score, grade, and a top-line take on each lens. Use it for a fast verdict or to compare versions.
+
+When to use each: summary for a fast verdict; moments to find the fix; per-second lens scores for the full timeline; per-second networks to know why; per-vertex fMRI for research and custom modeling.
+
+================================================================
+# Reading a scan
+
+A completed scan returns a result object.
+
+Score and grade: score is a 0–100 prediction of overall engagement; grade is the same signal as a letter (A–F). Treat them as relative — most useful when comparing two versions of the same content rather than as an absolute pass/fail.
+
+Lenses: lenses holds the seven reads (attention, purchase_intent, manipulation, emotion, cognitive_effort, memory, surprise), each 0–100. A high attention score with a low memory score, for example, means the content grabs focus but doesn't stick — a signal to strengthen the payoff.
+
+Raw: raw is for teams that want to go deeper — per-network activations, per-second time series, and composite breakdowns. Use it to find the exact second attention peaks or drops.

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@thesapientcompany/mcp",
+  "version": "0.1.0",
+  "description": "Model Context Protocol (MCP) server for the Sapient brain-response API — run scans, read your scan history, query cross-scan intelligence, and read the Sapient knowledge base from any MCP client.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "sapient-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "knowledge-base.txt",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "sapient",
+    "mcp",
+    "model-context-protocol",
+    "brain",
+    "fmri",
+    "neuro",
+    "advertising",
+    "ai"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.25.0 || ^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "typescript": "^5.5.0"
+  }
+}