psychosynth-mcp 0.1.0

package/README.md

@@ -0,0 +1,82 @@
+# psychosynth-mcp
+
+An [MCP](https://modelcontextprotocol.io) server that makes the **Psychosynth**
+synthetic psychometric data marketplace discoverable and usable by AI agents
+(Claude, OpenAI, and any MCP-compatible client).
+
+It exposes the public API as four tools: browse the catalog, fetch a free
+deterministic preview, get an x402 price quote, and run a paid query. Discovery
+tools are free and need no wallet; paid queries settle in USDC on Base using a
+wallet **you** configure.
+
+## Tools
+
+| Tool | Cost | Description |
+| --- | --- | --- |
+| `list_products` | free | List available data products with slugs, per-query prices, and bulk pack tiers. |
+| `preview_records` | free | Deterministic sample of a product's records — same rows every time, so you can verify quality before paying. |
+| `get_quote` | free | The x402 payment quote (price + accepted tiers) for a paid query, without paying. |
+| `query_records` | paid | Full records. Pays automatically over x402 using `BUYER_PRIVATE_KEY`; if unset, returns the quote instead. Add `tier` for a bulk pack. |
+
+## Install & configure
+
+The server is distributed on npm and run with `npx`. Add it to your MCP client.
+
+**Claude Desktop** (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "psychosynth": {
+      "command": "npx",
+      "args": ["-y", "psychosynth-mcp"],
+      "env": {
+        "PSYCHOSYNTH_API_URL": "https://your-deployment.example.com",
+        "BUYER_PRIVATE_KEY": "0xYOUR_BASE_WALLET_KEY"
+      }
+    }
+  }
+}
+```
+
+### Environment variables
+
+| Variable | Required | Purpose |
+| --- | --- | --- |
+| `PSYCHOSYNTH_API_URL` | no | Base URL of the Psychosynth deployment. Defaults to `http://localhost:3000`. |
+| `BUYER_PRIVATE_KEY` | no | Base (EVM) wallet key used to pay for queries. **Omit to use only the free tools.** |
+| `BASE_RPC_URL` | no | Custom Base RPC. Defaults to `https://mainnet.base.org`. |
+
+## Payment & safety
+
+- `list_products`, `preview_records`, and `get_quote` never touch a wallet.
+- `query_records` pays **only** with the key in `BUYER_PRIVATE_KEY`, which you
+  set. The server holds no other key and never moves funds on its own — if no
+  wallet is configured, a paid query returns the quote instead of paying.
+- Only keep enough USDC/ETH on the buyer wallet for expected spend. Treat the
+  key as a secret; never commit it.
+
+## How payment works
+
+`query_records` performs the standard x402 handshake: it requests the paid
+endpoint, receives a `402` quote, signs an EIP-3009 `TransferWithAuthorization`
+with your wallet (no gas on your side — the seller settles), and retries with
+the signed authorization. Base mainnet clock drift is compensated automatically
+so the authorization window is accepted.
+
+## Local development
+
+```bash
+npm install
+npm run build
+PSYCHOSYNTH_API_URL=http://localhost:3000 node dist/index.js
+```
+
+The server speaks MCP over stdio; run it from an MCP client rather than
+interacting directly.
+
+## Registry
+
+`server.json` is an [MCP registry](https://github.com/modelcontextprotocol/registry)
+manifest. Before publishing, replace `OWNER` with your GitHub namespace and
+publish `psychosynth-mcp` to npm.

package/dist/api.js

@@ -0,0 +1,27 @@
+// Thin HTTP client for the Psychosynth public API. Every endpoint used here
+// (catalog, preview, quote) is free and unauthenticated — no wallet involved.
+import { readBodySafe } from './util.js';
+export const API_BASE = (process.env.PSYCHOSYNTH_API_URL || 'https://psychosynth.vercel.app').replace(/\/+$/, '');
+export function buildQueryUrl(slug, filters) {
+    const url = new URL(`${API_BASE}/api/v1/query/${encodeURIComponent(slug)}`);
+    for (const [k, v] of Object.entries(filters ?? {})) {
+        if (v != null && v !== '')
+            url.searchParams.set(k, String(v));
+    }
+    return url.toString();
+}
+export async function getJson(url) {
+    const res = await fetch(url, { headers: { accept: 'application/json' } });
+    return { status: res.status, body: await readBodySafe(res) };
+}
+export async function listProducts() {
+    return getJson(`${API_BASE}/api/v1/products`);
+}
+export async function previewRecords(slug) {
+    return getJson(`${API_BASE}/api/v1/preview/${encodeURIComponent(slug)}`);
+}
+// Hitting the paid endpoint with no X-PAYMENT header returns the 402 quote
+// (price + available pack tiers). Pure discovery: no wallet, no money moved.
+export async function getQuote(slug, filters) {
+    return getJson(buildQueryUrl(slug, filters));
+}

package/dist/index.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { API_BASE, listProducts, previewRecords, getQuote, buildQueryUrl } from './api.js';
+import { payingFetch, hasBuyerWallet, buyerAddress } from './payment.js';
+const server = new McpServer({ name: 'psychosynth', version: '0.1.0' });
+// MCP tool results are text content blocks; JSON is stringified for the model.
+function result(payload) {
+    const text = typeof payload === 'string' ? payload : JSON.stringify(payload, null, 2);
+    return { content: [{ type: 'text', text }] };
+}
+// Shared input schema for the query-style tools. `filters` carries any
+// product-specific parameters (each product lists its allowed ones in
+// list_products); `tier` and `limit` are broken out for convenience.
+const querySchema = {
+    slug: z.string().describe("Product slug from list_products, e.g. 'behavioral-response-library'"),
+    tier: z
+        .string()
+        .optional()
+        .describe("Optional pack tier slug (e.g. 'pack-5k') for a bulk single-call result; omit for base per-query pricing"),
+    limit: z.string().optional().describe('Optional max number of records to return'),
+    filters: z
+        .record(z.string())
+        .optional()
+        .describe("Product-specific query filters, e.g. { category: 'trading' } or { mbti_label: 'INTJ' }. See each product's allowed parameters in list_products."),
+};
+function collectFilters(args) {
+    return {
+        ...(args.filters ?? {}),
+        ...(args.tier ? { tier: args.tier } : {}),
+        ...(args.limit ? { limit: args.limit } : {}),
+    };
+}
+server.registerTool('list_products', {
+    title: 'List products',
+    description: 'List the Psychosynth data products available for purchase (free, no wallet). Returns each product\'s slug, description, per-query price, and any bulk pack tiers. Start here to discover what can be queried.',
+    inputSchema: {},
+}, async () => {
+    const { status, body } = await listProducts();
+    if (status !== 200)
+        return result({ error: 'catalog request failed', status, body });
+    return result(body);
+});
+server.registerTool('preview_records', {
+    title: 'Preview records (free)',
+    description: 'Fetch a free, deterministic sample of a product\'s records so you can verify shape and quality before paying. The same product always returns the same preview rows. Provide a product slug from list_products.',
+    inputSchema: { slug: z.string().describe("Product slug, e.g. 'behavioral-response-library'") },
+}, async ({ slug }) => {
+    const { status, body } = await previewRecords(slug);
+    if (status !== 200)
+        return result({ error: 'preview request failed', status, body });
+    return result(body);
+});
+server.registerTool('get_quote', {
+    title: 'Get price quote (free)',
+    description: 'Get the x402 payment quote for a paid query WITHOUT paying — returns the price, accepted payment details, and available pack tiers. No wallet required. Use this to see the exact cost before calling query_records.',
+    inputSchema: querySchema,
+}, async (args) => {
+    const { status, body } = await getQuote(args.slug, collectFilters(args));
+    return result({
+        note: status === 402 ? '402 quote — payment required to fetch records' : `status ${status}`,
+        quote: body,
+    });
+});
+server.registerTool('query_records', {
+    title: 'Query records (paid via x402)',
+    description: 'Run a paid query and return the full records. Pays automatically over x402 (USDC on Base) using the wallet in the BUYER_PRIVATE_KEY environment variable. If no wallet is configured, returns the price quote instead so you can review the cost first. Add `tier` for a bulk pack.',
+    inputSchema: querySchema,
+}, async (args) => {
+    const filters = collectFilters(args);
+    if (!hasBuyerWallet()) {
+        const { status, body } = await getQuote(args.slug, filters);
+        return result({
+            error: 'No buyer wallet configured. Set BUYER_PRIVATE_KEY to enable paid queries.',
+            status,
+            quote: body,
+        });
+    }
+    try {
+        const { status, body } = await payingFetch(buildQueryUrl(args.slug, filters));
+        if (status !== 200)
+            return result({ error: 'paid query failed', status, body });
+        return result(body);
+    }
+    catch (e) {
+        return result({ error: 'payment/query error', message: e?.message ?? String(e) });
+    }
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // stdout is reserved for the MCP protocol; log to stderr only.
+    console.error(`psychosynth-mcp connected. API=${API_BASE} wallet=${hasBuyerWallet() ? buyerAddress() : 'not configured (free tools only)'}`);
+}
+main().catch((e) => {
+    console.error('fatal:', e);
+    process.exit(1);
+});

package/dist/payment.js

@@ -0,0 +1,53 @@
+import { createPublicClient, createWalletClient, http, publicActions } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import { base } from 'viem/chains';
+import { wrapFetchWithPayment } from 'x402-fetch';
+import { readBodySafe } from './util.js';
+const RPC = process.env.BASE_RPC_URL || 'https://mainnet.base.org';
+function buyerKey() {
+    const pk = process.env.BUYER_PRIVATE_KEY;
+    if (!pk)
+        return undefined;
+    return (pk.startsWith('0x') ? pk : `0x${pk}`);
+}
+export function hasBuyerWallet() {
+    return !!buyerKey();
+}
+export function buyerAddress() {
+    const pk = buyerKey();
+    if (!pk)
+        return null;
+    try {
+        return privateKeyToAccount(pk).address;
+    }
+    catch {
+        return null;
+    }
+}
+// Paid fetch using the operator's OWN wallet key (BUYER_PRIVATE_KEY). The server
+// never holds any other key and never moves funds on its own — a paid query
+// only happens when the operator has explicitly configured their wallet.
+// Mirrors scripts/buyer-test.ts, including Base clock-drift compensation, which
+// keeps the EIP-3009 validAfter/validBefore window inside what the chain accepts.
+export async function payingFetch(url) {
+    const pk = buyerKey();
+    if (!pk)
+        throw new Error('BUYER_PRIVATE_KEY not set');
+    const publicClient = createPublicClient({ chain: base, transport: http(RPC) });
+    const block = await publicClient.getBlock();
+    const driftSeconds = Math.floor(Date.now() / 1000) - Number(block.timestamp);
+    const account = privateKeyToAccount(pk);
+    const client = createWalletClient({ account, chain: base, transport: http(RPC) }).extend(publicActions);
+    const fetchWithPay = wrapFetchWithPayment(fetch, client);
+    // Compensate for local/chain clock drift (+5m safety) so validAfter is in the
+    // past when the settlement contract checks it. Restored immediately after.
+    const originalNow = Date.now;
+    Date.now = () => originalNow() - (driftSeconds + 300) * 1000;
+    try {
+        const res = await fetchWithPay(url);
+        return { status: res.status, body: await readBodySafe(res) };
+    }
+    finally {
+        Date.now = originalNow;
+    }
+}

package/dist/util.js

@@ -0,0 +1,16 @@
+// Read a fetch Response body as JSON, falling back to text, then null.
+// Used for both free API calls and paid (x402) responses, which may return
+// JSON on success and JSON or text on error/402.
+export async function readBodySafe(res) {
+    try {
+        return await res.json();
+    }
+    catch {
+        try {
+            return await res.text();
+        }
+        catch {
+            return null;
+        }
+    }
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "psychosynth-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for the Psychosynth synthetic psychometric data marketplace — discover the catalog, fetch free deterministic previews, get x402 price quotes, and run paid queries with your own wallet.",
+  "type": "module",
+  "bin": {
+    "psychosynth-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "server.json"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsc --watch"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "modelcontextprotocol",
+    "x402",
+    "psychometric",
+    "synthetic-data",
+    "agents"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "viem": "^2.55.0",
+    "x402-fetch": "^1.2.0",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "typescript": "^5"
+  }
+}

package/server.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
+  "name": "io.github.3esign/psychosynth",
+  "description": "Discover and query Psychosynth synthetic psychometric data (Big Five profiles, cognitive biases, profile-conditioned behavioral responses) over the x402 protocol. Free catalog, free deterministic previews, and price quotes; paid queries settle in USDC on Base using your own wallet.",
+  "repository": {
+    "url": "https://github.com/3esign/cfaces",
+    "source": "github"
+  },
+  "version": "0.1.0",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "psychosynth-mcp",
+      "version": "0.1.0",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "PSYCHOSYNTH_API_URL",
+          "description": "Base URL of the Psychosynth API deployment (e.g. https://your-app.vercel.app). Defaults to http://localhost:3000 for local development.",
+          "isRequired": false,
+          "isSecret": false
+        },
+        {
+          "name": "BUYER_PRIVATE_KEY",
+          "description": "Base (EVM) wallet private key used to pay for queries via x402. Omit to use only the free catalog, preview, and quote tools.",
+          "isRequired": false,
+          "isSecret": true
+        },
+        {
+          "name": "BASE_RPC_URL",
+          "description": "Optional custom Base mainnet RPC endpoint. Defaults to https://mainnet.base.org.",
+          "isRequired": false,
+          "isSecret": false
+        }
+      ]
+    }
+  ]
+}