@agentic-survey/mcp-server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 netmonty
+
+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,68 @@
+# @agentic-survey/mcp-server
+
+An open-source ([MIT](./LICENSE)) [MCP](https://modelcontextprotocol.io) server that lets your own AI agent **build surveys and read results**, straight into **your own Supabase**. You own the data, you carry the AI cost, and your keys never leave your machine. It's free.
+
+Part of [agentic-survey-mcp](https://github.com/netmonty/agentic-survey-mcp). Site: [mcpsurveys.com](https://www.mcpsurveys.com).
+
+## Why
+
+- **You own the data.** Surveys, questions, and responses live in *your* Supabase project. Nothing is stored on anyone else's infrastructure.
+- **You carry the AI cost.** Authoring and analysis happen inside *your* agent. There's no AI running server-side, so there's nothing to bill you for.
+- **Bring your own keys.** Your Supabase secret key stays in a local config file. It's never transmitted, never logged, and never a tool argument the agent can read.
+
+## Quick start
+
+```bash
+# 1. Print the schema, paste it into your Supabase SQL editor
+npx -y @agentic-survey/mcp-server init --print-sql
+
+# 2. Store your keys locally and verify the connection
+#    (typed into your terminal, never sent to the agent)
+npx -y @agentic-survey/mcp-server init
+```
+
+Then point your MCP client at the server:
+
+```bash
+# Claude Code
+claude mcp add agentic-survey -- npx -y @agentic-survey/mcp-server
+```
+
+```jsonc
+// Claude Desktop / Cursor / other (claude_desktop_config.json, .cursor/mcp.json, ...)
+{
+  "mcpServers": {
+    "agentic-survey": { "command": "npx", "args": ["-y", "@agentic-survey/mcp-server"] }
+  }
+}
+```
+
+Now just talk to your agent:
+
+> "Build a 4-question customer-satisfaction survey with a 1-5 rating, a yes/no, a multiple choice, and an open comment. Publish it and give me the share link."
+
+> "Summarise the results so far, themes from the comments too."
+
+The agent chains the tools for you: `create_survey` → `add_question` → `publish_survey` → `get_results`.
+
+> Tip: `npm i -g @agentic-survey/mcp-server` gives you the shorter `agentic-survey init` command.
+
+## How it works
+
+```
+  your AI agent ──(MCP / stdio)──▶  mcp-server ──┐
+                                                  ├──▶  your Supabase
+  respondent ──(browser)──▶  page-service ────────┘     (source of truth)
+```
+
+Publishing a survey returns a share link carrying your project ref and publishable key. A respondent opens it, the stateless page-service writes their answers into your Supabase, and your agent reads them back with `get_results`. Supabase is the backend for now; more are planned.
+
+## Tools
+
+`setup_connection`, `create_survey`, `add_question`, `update_question`, `remove_question`, `reorder_questions`, `publish_survey`, `get_share_link`, `list_surveys`, `get_survey`, `list_responses`, `get_results`.
+
+Question types: `single_choice`, `multi_choice`, `rating`, `yes_no`, `number`, `short_text`, `long_text`.
+
+## License
+
+[MIT](./LICENSE). Built by [Monty](https://montymakesthings.com). Source and issues on [GitHub](https://github.com/netmonty/agentic-survey-mcp).

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+import readline from 'node:readline';
+import { readInitialMigrationSql } from '@agentic-survey/schema';
+import { createDb, listSurveys, isErr } from '@agentic-survey/core';
+import { runServer } from './index.js';
+import { saveConfig, loadConfig, configPath, projectRefFromUrl, DEFAULT_PAGE_ENDPOINT, } from './config.js';
+function parseFlags(argv) {
+    const out = {};
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (!a.startsWith('--'))
+            continue;
+        const key = a.slice(2);
+        const next = argv[i + 1];
+        if (next && !next.startsWith('--')) {
+            out[key] = next;
+            i++;
+        }
+        else {
+            out[key] = true;
+        }
+    }
+    return out;
+}
+/** Prompt; when hidden, the typed characters are not echoed. */
+function ask(query, hidden = false) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout, terminal: true });
+    if (hidden) {
+        let shownPrompt = false;
+        rl._writeToOutput = (s) => {
+            if (!shownPrompt) {
+                rl.output.write(s);
+                shownPrompt = true;
+            }
+            // mute keystroke echoes
+        };
+    }
+    return new Promise((resolve) => {
+        rl.question(query, (answer) => {
+            if (hidden)
+                rl.output.write('\n');
+            rl.close();
+            resolve(answer.trim());
+        });
+    });
+}
+function printAgentSnippet() {
+    const snippet = {
+        mcpServers: {
+            'agentic-survey': {
+                command: 'npx',
+                args: ['-y', '@agentic-survey/mcp-server'],
+            },
+        },
+    };
+    console.log('\nAdd this to your agent config (e.g. Claude Desktop):\n');
+    console.log(JSON.stringify(snippet, null, 2));
+}
+async function runInit(flags) {
+    if (flags['print-sql']) {
+        process.stdout.write(readInitialMigrationSql());
+        return;
+    }
+    console.log('agentic-survey init — your keys are stored locally and never transmitted.\n');
+    const existing = loadConfig();
+    const supabaseUrl = flags.url ||
+        (await ask(`Supabase project URL${existing.supabaseUrl ? ` [${existing.supabaseUrl}]` : ''}: `)) ||
+        existing.supabaseUrl ||
+        '';
+    const secretKey = flags['secret-key'] ||
+        (await ask('Supabase SECRET key (sb_secret_…, hidden): ', true)) ||
+        existing.secretKey ||
+        '';
+    const publishableKey = flags['publishable-key'] ||
+        (await ask(`Supabase publishable key (sb_publishable_…, optional${existing.publishableKey ? ', set' : ''}): `)) ||
+        existing.publishableKey ||
+        '';
+    const pageEndpoint = flags['page-endpoint'] ||
+        (await ask(`Page-service endpoint [${existing.pageEndpoint ?? DEFAULT_PAGE_ENDPOINT}]: `)) ||
+        existing.pageEndpoint ||
+        DEFAULT_PAGE_ENDPOINT;
+    if (!supabaseUrl || !secretKey) {
+        console.error('\nA project URL and secret key are required. Aborting.');
+        process.exitCode = 1;
+        return;
+    }
+    const cfg = {
+        supabaseUrl,
+        secretKey,
+        publishableKey: publishableKey || undefined,
+        pageEndpoint,
+    };
+    const path = saveConfig(cfg);
+    console.log(`\nSaved config to ${path} (mode 0600).`);
+    const ref = projectRefFromUrl(supabaseUrl);
+    console.log(`Project ref: ${ref ?? '(could not parse from URL)'}`);
+    // Verify the schema is present.
+    const db = createDb(supabaseUrl, secretKey);
+    const probe = await listSurveys(db, {});
+    if (isErr(probe)) {
+        console.log('\n⚠  Could not read the survey schema — it may not be installed yet.');
+        console.log('   Install it one of these ways:');
+        console.log('     1) Run `npx agentic-survey init --print-sql` and paste the output into');
+        console.log('        the Supabase SQL editor.');
+        console.log('     2) `supabase db push`, or apply via the Supabase MCP.');
+    }
+    else {
+        console.log(`\n✓ Connected. Schema present (${probe.data.length} survey(s)).`);
+    }
+    printAgentSnippet();
+}
+async function main() {
+    const [cmd, ...rest] = process.argv.slice(2);
+    const flags = parseFlags(rest);
+    switch (cmd) {
+        // Default (no command) = serve: this is what the agent launches via the MCP config.
+        case undefined:
+        case 'serve':
+            await runServer();
+            break;
+        case 'init':
+            await runInit(flags);
+            break;
+        default:
+            console.error(`Unknown command: ${cmd}\nUsage:\n  agentic-survey            start the MCP server (stdio)\n  agentic-survey init [--print-sql]   set up / print schema SQL`);
+            process.exitCode = 1;
+    }
+}
+main().catch((e) => {
+    console.error(`fatal: ${e instanceof Error ? e.message : String(e)}`);
+    process.exit(1);
+});

package/dist/config.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Connection config. The SECRET key lives only here (local file) or in env —
+ * it is NEVER accepted as an MCP tool argument, so it never reaches the agent
+ * or model provider. See docs/trust-model.md.
+ */
+export interface StoredConfig {
+    supabaseUrl: string;
+    secretKey: string;
+    publishableKey?: string;
+    /** Page-service base URL; defaults to the author's hosted instance. */
+    pageEndpoint?: string;
+}
+export declare const DEFAULT_PAGE_ENDPOINT = "https://agentic-survey-pages.vercel.app";
+export declare function configPath(): string;
+/** Derive the Supabase project ref from the project URL. */
+export declare function projectRefFromUrl(url: string): string | undefined;
+/**
+ * Resolution order (per the brief): explicit args → local config file → env.
+ * The server has no explicit secret args, so: file values win, env fills gaps.
+ */
+export declare function loadConfig(): Partial<StoredConfig>;
+export declare function saveConfig(cfg: StoredConfig): string;
+/** A config is "connectable" once it has a URL + secret key. */
+export declare function isConnectable(cfg: Partial<StoredConfig>): cfg is StoredConfig;

package/dist/config.js

@@ -0,0 +1,61 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync, chmodSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+export const DEFAULT_PAGE_ENDPOINT = 'https://agentic-survey-pages.vercel.app';
+export function configPath() {
+    const base = process.env.AGENTIC_SURVEY_CONFIG ??
+        join(process.env.XDG_CONFIG_HOME ?? join(homedir(), '.config'), 'agentic-survey', 'config.json');
+    return base;
+}
+/** Derive the Supabase project ref from the project URL. */
+export function projectRefFromUrl(url) {
+    const m = url.match(/^https?:\/\/([a-z0-9]+)\.supabase\.(co|in|net)/i);
+    return m?.[1];
+}
+function readFile() {
+    const p = configPath();
+    if (!existsSync(p))
+        return {};
+    try {
+        return JSON.parse(readFileSync(p, 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Resolution order (per the brief): explicit args → local config file → env.
+ * The server has no explicit secret args, so: file values win, env fills gaps.
+ */
+export function loadConfig() {
+    const fromEnv = {
+        supabaseUrl: process.env.SUPABASE_URL,
+        secretKey: process.env.SUPABASE_SECRET_KEY,
+        publishableKey: process.env.SUPABASE_PUBLISHABLE_KEY,
+        pageEndpoint: process.env.AGENTIC_SURVEY_PAGE_ENDPOINT,
+    };
+    const fromFile = readFile();
+    // Drop undefined so file values aren't clobbered by missing env keys.
+    const merged = { ...fromEnv };
+    for (const [k, v] of Object.entries(fromFile)) {
+        if (v !== undefined && v !== '')
+            merged[k] = v;
+    }
+    return merged;
+}
+export function saveConfig(cfg) {
+    const p = configPath();
+    mkdirSync(dirname(p), { recursive: true });
+    writeFileSync(p, JSON.stringify(cfg, null, 2) + '\n', { mode: 0o600 });
+    try {
+        chmodSync(p, 0o600); // ensure perms even if the file pre-existed
+    }
+    catch {
+        /* best effort */
+    }
+    return p;
+}
+/** A config is "connectable" once it has a URL + secret key. */
+export function isConnectable(cfg) {
+    return Boolean(cfg.supabaseUrl && cfg.secretKey);
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { buildServer } from './server.js';
+/** Start the MCP server over stdio. */
+export declare function runServer(): Promise<void>;

package/dist/index.js

@@ -0,0 +1,11 @@
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { buildServer } from './server.js';
+export { buildServer } from './server.js';
+/** Start the MCP server over stdio. */
+export async function runServer() {
+    const server = buildServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // stdio transport keeps the process alive; log to stderr (stdout is the protocol).
+    process.stderr.write('agentic-survey MCP server running on stdio\n');
+}

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function buildServer(): McpServer;

package/dist/server.js

@@ -0,0 +1,286 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { createDb, createSurvey, updateSurvey, publishSurvey, closeSurvey, listSurveys, getSurvey, addQuestion, updateQuestion, removeQuestion, reorderQuestions, listResponses, getResults, buildShareUrl, isErr, } from '@agentic-survey/core';
+import { readInitialMigrationSql } from '@agentic-survey/schema';
+import { loadConfig, isConnectable, projectRefFromUrl, configPath, DEFAULT_PAGE_ENDPOINT, } from './config.js';
+const QUESTION_TYPE = z.enum([
+    'single_choice',
+    'multi_choice',
+    'short_text',
+    'long_text',
+    'rating',
+    'yes_no',
+    'number',
+]);
+const SURVEY_STATUS = z.enum(['draft', 'published', 'closed']);
+const ok = (summary, data) => ({
+    content: [{ type: 'text', text: summary }],
+    structuredContent: data,
+});
+const fail = (code, message) => ({
+    content: [{ type: 'text', text: `Error (${code}): ${message}` }],
+    structuredContent: { error: { code, message } },
+    isError: true,
+});
+const NOT_CONNECTED = fail('not_connected', 'No Supabase connection configured. Run `npx agentic-survey init` (it stores your keys locally — never paste them into the agent), then retry.');
+/** Resolve a live connection from local config/env, or a typed error result. */
+function getConn() {
+    const cfg = loadConfig();
+    if (!isConnectable(cfg))
+        return { ok: false, res: NOT_CONNECTED };
+    return { ok: true, db: createDb(cfg.supabaseUrl, cfg.secretKey), cfg };
+}
+function linkConfig(cfg) {
+    const projectRef = projectRefFromUrl(cfg.supabaseUrl);
+    if (!projectRef || !cfg.publishableKey)
+        return undefined;
+    return {
+        pageEndpoint: cfg.pageEndpoint ?? DEFAULT_PAGE_ENDPOINT,
+        projectRef,
+        publishableKey: cfg.publishableKey,
+    };
+}
+export function buildServer() {
+    const server = new McpServer({ name: 'agentic-survey', version: '0.0.0' });
+    server.registerTool('setup_connection', {
+        title: 'Set up / verify Supabase connection',
+        description: 'Verify the locally-configured Supabase connection and that the survey schema is present. ' +
+            'Does NOT accept keys as arguments — keys are configured via `npx agentic-survey init` and stored ' +
+            'locally. If the schema is missing, returns the SQL to run (paste into the Supabase SQL editor, or use ' +
+            '`supabase db push` / the Supabase MCP). Call this first if other tools report not_connected.',
+        inputSchema: {},
+        annotations: { readOnlyHint: true },
+    }, async () => {
+        const cfg = loadConfig();
+        if (!isConnectable(cfg)) {
+            return ok('Not connected.', {
+                connected: false,
+                configPath: configPath(),
+                next: 'Run `npx agentic-survey init` to store your Supabase URL + secret key locally.',
+            });
+        }
+        const db = createDb(cfg.supabaseUrl, cfg.secretKey);
+        const probe = await listSurveys(db, {});
+        if (isErr(probe)) {
+            return ok('Connected, but the survey schema is missing.', {
+                connected: true,
+                schemaPresent: false,
+                error: probe.error,
+                migrationSql: readInitialMigrationSql(),
+                next: 'Run the migrationSql in the Supabase SQL editor (or `supabase db push` / the Supabase MCP).',
+            });
+        }
+        return ok(`Connected. Schema present. ${probe.data.length} survey(s) found.`, {
+            connected: true,
+            schemaPresent: true,
+            surveyCount: probe.data.length,
+            publishableKeyConfigured: Boolean(cfg.publishableKey),
+        });
+    });
+    server.registerTool('create_survey', {
+        title: 'Create a draft survey',
+        description: 'Create a new draft survey. Returns its id. Typical flow: create_survey → add_question (×N) → ' +
+            'publish_survey → get_share_link.',
+        inputSchema: {
+            title: z.string().min(1).describe('Survey title'),
+            description: z.string().optional().describe('Optional description'),
+        },
+    }, async ({ title, description }) => {
+        const c = getConn();
+        if (!c.ok)
+            return c.res;
+        const r = await createSurvey(c.db, { title, description });
+        if (isErr(r))
+            return fail(r.error.code, r.error.message);
+        return ok(`Created draft survey "${r.data.title}" (id ${r.data.id}).`, { survey: r.data });
+    });
+    server.registerTool('add_question', {
+        title: 'Add a question to a survey',
+        description: 'Append (or insert at `position`) a question. `config` shape depends on `type`: ' +
+            'single_choice/multi_choice → { options: [{ id, label }] }; rating → { min, max }; ' +
+            'number → { min?, max?, step?, unit? }; short_text/long_text → { placeholder?, maxLength? }; ' +
+            'yes_no → {}. Give each choice option a stable `id`.',
+        inputSchema: {
+            surveyId: z.string(),
+            type: QUESTION_TYPE,
+            prompt: z.string().min(1),
+            required: z.boolean().optional(),
+            config: z.record(z.string(), z.unknown()).optional().describe('Per-type config (see description)'),
+            position: z.number().int().min(0).optional(),
+        },
+    }, async ({ surveyId, type, prompt, required, config, position }) => {
+        const c = getConn();
+        if (!c.ok)
+            return c.res;
+        const r = await addQuestion(c.db, surveyId, {
+            type,
+            prompt,
+            required,
+            config: config,
+            position,
+        });
+        if (isErr(r))
+            return fail(r.error.code, r.error.message);
+        return ok(`Added ${type} question at position ${r.data.position}.`, { question: r.data });
+    });
+    server.registerTool('update_question', {
+        title: 'Update a question',
+        description: 'Patch a question (prompt, type, required, config, position). Only provided fields change.',
+        inputSchema: {
+            questionId: z.string(),
+            prompt: z.string().min(1).optional(),
+            type: QUESTION_TYPE.optional(),
+            required: z.boolean().optional(),
+            config: z.record(z.string(), z.unknown()).optional(),
+            position: z.number().int().min(0).optional(),
+        },
+    }, async ({ questionId, ...patch }) => {
+        const c = getConn();
+        if (!c.ok)
+            return c.res;
+        const r = await updateQuestion(c.db, questionId, patch);
+        if (isErr(r))
+            return fail(r.error.code, r.error.message);
+        return ok('Question updated.', { question: r.data });
+    });
+    server.registerTool('remove_question', {
+        title: 'Remove a question',
+        description: 'Delete a question from a survey.',
+        inputSchema: { questionId: z.string() },
+        annotations: { destructiveHint: true },
+    }, async ({ questionId }) => {
+        const c = getConn();
+        if (!c.ok)
+            return c.res;
+        const r = await removeQuestion(c.db, questionId);
+        if (isErr(r))
+            return fail(r.error.code, r.error.message);
+        return ok('Question removed.', { removed: true });
+    });
+    server.registerTool('reorder_questions', {
+        title: 'Reorder a survey’s questions',
+        description: 'Set question order to match `orderedIds` (positions become array index).',
+        inputSchema: { surveyId: z.string(), orderedIds: z.array(z.string()).min(1) },
+    }, async ({ surveyId, orderedIds }) => {
+        const c = getConn();
+        if (!c.ok)
+            return c.res;
+        const r = await reorderQuestions(c.db, surveyId, orderedIds);
+        if (isErr(r))
+            return fail(r.error.code, r.error.message);
+        return ok('Questions reordered.', { reordered: true });
+    });
+    server.registerTool('publish_survey', {
+        title: 'Publish a survey',
+        description: 'Publish a draft survey and return its public share link (if a publishable key is configured). ' +
+            'Respondents can then open the link and submit.',
+        inputSchema: { surveyId: z.string() },
+    }, async ({ surveyId }) => {
+        const c = getConn();
+        if (!c.ok)
+            return c.res;
+        const r = await publishSurvey(c.db, surveyId, linkConfig(c.cfg));
+        if (isErr(r))
+            return fail(r.error.code, r.error.message);
+        const note = r.data.shareUrl
+            ? `Share link: ${r.data.shareUrl}`
+            : 'Published, but no share link — configure a publishable key (re-run `init`) to enable public links.';
+        return ok(`Published "${r.data.survey.title}". ${note}`, {
+            survey: r.data.survey,
+            shareUrl: r.data.shareUrl ?? null,
+        });
+    });
+    server.registerTool('get_share_link', {
+        title: 'Get a published survey’s share link',
+        description: 'Return the public link for a published survey.',
+        inputSchema: { surveyId: z.string() },
+        annotations: { readOnlyHint: true },
+    }, async ({ surveyId }) => {
+        const c = getConn();
+        if (!c.ok)
+            return c.res;
+        const r = await getSurvey(c.db, surveyId);
+        if (isErr(r))
+            return fail(r.error.code, r.error.message);
+        if (r.data.survey.status !== 'published') {
+            return fail('not_published', `Survey is ${r.data.survey.status}; publish it first.`);
+        }
+        const link = linkConfig(c.cfg);
+        if (!link)
+            return fail('no_publishable_key', 'No publishable key configured; re-run `init`.');
+        return ok('Share link ready.', { shareUrl: buildShareUrl(link, surveyId) });
+    });
+    server.registerTool('list_surveys', {
+        title: 'List surveys',
+        description: 'List surveys, optionally filtered by status.',
+        inputSchema: { status: SURVEY_STATUS.optional() },
+        annotations: { readOnlyHint: true },
+    }, async ({ status }) => {
+        const c = getConn();
+        if (!c.ok)
+            return c.res;
+        const r = await listSurveys(c.db, { status });
+        if (isErr(r))
+            return fail(r.error.code, r.error.message);
+        return ok(`${r.data.length} survey(s).`, { surveys: r.data });
+    });
+    server.registerTool('get_survey', {
+        title: 'Get a survey’s full definition',
+        description: 'Return a survey plus its ordered questions.',
+        inputSchema: { surveyId: z.string() },
+        annotations: { readOnlyHint: true },
+    }, async ({ surveyId }) => {
+        const c = getConn();
+        if (!c.ok)
+            return c.res;
+        const r = await getSurvey(c.db, surveyId);
+        if (isErr(r))
+            return fail(r.error.code, r.error.message);
+        return ok(`"${r.data.survey.title}" — ${r.data.questions.length} question(s).`, {
+            survey: r.data.survey,
+            questions: r.data.questions,
+        });
+    });
+    server.registerTool('list_responses', {
+        title: 'List raw responses (paginated)',
+        description: 'Cursor-paginated raw responses with answers. Pass the returned nextCursor to page.',
+        inputSchema: {
+            surveyId: z.string(),
+            limit: z.number().int().min(1).max(200).optional(),
+            cursor: z.string().optional(),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ surveyId, limit, cursor }) => {
+        const c = getConn();
+        if (!c.ok)
+            return c.res;
+        const r = await listResponses(c.db, surveyId, { limit, cursor });
+        if (isErr(r))
+            return fail(r.error.code, r.error.message);
+        return ok(`${r.data.responses.length} response(s).`, {
+            responses: r.data.responses,
+            nextCursor: r.data.nextCursor,
+        });
+    });
+    server.registerTool('get_results', {
+        title: 'Get survey results (aggregates + raw)',
+        description: 'Return pre-computed aggregates over ALL responses (counts/percentages for choices; ' +
+            'mean/median/min/max/distribution for ratings & numbers; raw text for text questions) PLUS a ' +
+            'paginated page of raw responses. Use the aggregates for summaries; theme the raw text yourself.',
+        inputSchema: {
+            surveyId: z.string(),
+            responsesLimit: z.number().int().min(1).max(200).optional(),
+            cursor: z.string().optional(),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ surveyId, responsesLimit, cursor }) => {
+        const c = getConn();
+        if (!c.ok)
+            return c.res;
+        const r = await getResults(c.db, surveyId, { responsesLimit, cursor });
+        if (isErr(r))
+            return fail(r.error.code, r.error.message);
+        return ok(`Results for "${r.data.survey.title}": ${r.data.survey.responseCount} response(s).`, r.data);
+    });
+    return server;
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@agentic-survey/mcp-server",
+  "version": "0.1.0",
+  "description": "MCP server (stdio) exposing survey tools over core, plus the agentic-survey CLI.",
+  "license": "MIT",
+  "author": "Monty Daley <monty@daley.org.nz>",
+  "homepage": "https://www.mcpsurveys.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/netmonty/agentic-survey-mcp.git",
+    "directory": "packages/mcp-server"
+  },
+  "bugs": "https://github.com/netmonty/agentic-survey-mcp/issues",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "survey",
+    "surveys",
+    "supabase",
+    "ai-agent",
+    "forms",
+    "cli"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "agentic-survey": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "start": "node --import tsx src/cli.ts",
+    "test": "node --import tsx --env-file-if-exists=../../.env --test src/**/*.test.ts",
+    "prepublishOnly": "tsc -b"
+  },
+  "dependencies": {
+    "@agentic-survey/core": "^0.1.0",
+    "@agentic-survey/schema": "^0.1.0",
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.0"
+  }
+}