@sampuli/mcp 0.1.0

package/README.md

@@ -0,0 +1,67 @@
+# @sampuli/mcp
+
+**Generate format-true synthetic test data for 90 countries — right inside your AI assistant.**
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server for [Sampuli](https://sampuli.site). Ask Claude, Cursor, Copilot or any MCP client to *"generate 50 German customers with valid IBANs"* and get data back inline — national IDs, tax numbers, IBANs, SWIFT/BIC, payment cards, phone numbers and full KYC records, each correct for its own country and passing real validators (IBAN mod-97, card Luhn, …).
+
+Entirely synthetic: real formats, never real or registered data. Same engine as the [`@sampuli/data`](https://www.npmjs.com/package/@sampuli/data) npm package and [sampuli.site](https://sampuli.site).
+
+## Tools
+
+| Tool | What it does |
+| --- | --- |
+| `sampuli_list_countries` | List all 90 countries and their codes |
+| `sampuli_describe_country` | A country's fields and preset scenarios |
+| `sampuli_generate` | Generate data — `spec`, `count`, `fields`, `seed`, `format` |
+
+`spec` is `<country>.<selector>`, where the selector is a field key (`ke.phone`), `person` for a full record (`de.person`), or `preset:<key>` for a scenario (`ke.preset:kyc`).
+
+## Install
+
+No install needed — `npx` runs it on demand.
+
+### Claude Desktop / Claude Code
+
+Add to your MCP config (`claude_desktop_config.json`, or `.mcp.json` in a project):
+
+```json
+{
+  "mcpServers": {
+    "sampuli": {
+      "command": "npx",
+      "args": ["-y", "@sampuli/mcp"]
+    }
+  }
+}
+```
+
+### Cursor
+
+`~/.cursor/mcp.json` (or **Settings → MCP → Add**):
+
+```json
+{
+  "mcpServers": {
+    "sampuli": { "command": "npx", "args": ["-y", "@sampuli/mcp"] }
+  }
+}
+```
+
+Restart the client, then ask it to generate test data.
+
+## Try it
+
+> "List every country Sampuli supports."
+> "Generate 100 Nigerian people with name, phone and BVN as CSV."
+> "Give me one UK IBAN and one German test card number."
+> "Generate a Kenyan KYC scenario."
+
+## Prefer a URL or an install?
+
+- **REST API** (no key): `curl https://sampuli.site/api/v1/ke/person?n=100`
+- **npm**: `npm i @sampuli/data`
+- **Browser**: [sampuli.site](https://sampuli.site)
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@sampuli/mcp",
+  "version": "0.1.0",
+  "description": "Model Context Protocol server for Sampuli — generate format-true synthetic test data for 90 countries directly inside Claude, Cursor, Copilot and any MCP client.",
+  "type": "module",
+  "main": "./src/server.js",
+  "bin": {
+    "sampuli-mcp": "./src/bin.js"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "start": "node src/bin.js",
+    "test": "vitest run"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "cursor",
+    "copilot",
+    "test-data",
+    "synthetic-data",
+    "fake-data",
+    "iban",
+    "fintech",
+    "sampuli"
+  ],
+  "author": "Sampuli",
+  "license": "MIT",
+  "homepage": "https://sampuli.site",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kevinbett/sampuli.git",
+    "directory": "packages/mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/kevinbett/sampuli/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@sampuli/data": "^0.3.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "vitest": "^2.1.9"
+  }
+}

package/src/bin.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+// Entry point: start the Sampuli MCP server over stdio.
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { createServer } from './server.js'
+
+const server = createServer()
+const transport = new StdioServerTransport()
+await server.connect(transport)
+// stderr is safe for logs; stdout is the MCP channel.
+console.error('sampuli-mcp: ready (stdio)')

package/src/server.js

@@ -0,0 +1,54 @@
+// Sampuli MCP server — exposes the synthetic-data engine as Model Context
+// Protocol tools so any MCP client (Claude Desktop, Cursor, Copilot, …) can
+// generate format-true test data inline. Transport is stdio (see bin.js).
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { z } from 'zod'
+import { listCountries, describeCountry, generateData } from './tools.js'
+
+export function createServer() {
+  const server = new McpServer({
+    name: 'sampuli',
+    version: '0.1.0',
+  })
+
+  server.registerTool(
+    'sampuli_list_countries',
+    {
+      title: 'List Sampuli countries',
+      description: 'List every country Sampuli can generate synthetic test data for (90 countries), with the ISO code used as a spec prefix.',
+      inputSchema: {},
+    },
+    async () => listCountries(),
+  )
+
+  server.registerTool(
+    'sampuli_describe_country',
+    {
+      title: 'Describe a country',
+      description: "List a country's available fields (phone, national ID, tax number, IBAN, SWIFT/BIC, card, …) and preset scenarios.",
+      inputSchema: {
+        country: z.string().describe('ISO code, e.g. "ke", "de", "us", "ng".'),
+      },
+    },
+    async args => describeCountry(args),
+  )
+
+  server.registerTool(
+    'sampuli_generate',
+    {
+      title: 'Generate synthetic test data',
+      description:
+        'Generate format-true, entirely synthetic test data for a country. spec is "<country>.<selector>" where selector is a field key ("phone"), "person" (a full coherent record), or "preset:<key>" (a scenario). Values match each country\'s real formats and pass validators (IBAN mod-97, card Luhn, …) but are never real or registered.',
+      inputSchema: {
+        spec: z.string().describe('e.g. "ke.person", "de.iban", "ng.phone", "ke.preset:kyc".'),
+        count: z.number().int().min(1).max(10000).optional().describe('How many rows (omit for one).'),
+        fields: z.union([z.array(z.string()), z.literal('all')]).optional().describe('Which fields for a person record, or "all".'),
+        seed: z.string().optional().describe('Reproducible output — same seed, same data.'),
+        format: z.enum(['json', 'csv']).optional().describe('Output format (default json).'),
+      },
+    },
+    async args => generateData(args),
+  )
+
+  return server
+}

package/src/tools.js

@@ -0,0 +1,66 @@
+// Pure tool implementations for the Sampuli MCP server.
+// Kept separate from the transport so they can be unit-tested directly.
+// Each returns a Model Context Protocol tool result: { content: [...], isError? }.
+import { generate, generateMany, listPacks, listFields, listPresets } from '@sampuli/data'
+
+const text = t => ({ content: [{ type: 'text', text: t }] })
+const fail = t => ({ content: [{ type: 'text', text: t }], isError: true })
+
+const csvCell = v => { const s = v == null ? '' : String(v); return /[",\n]/.test(s) ? '"' + s.replace(/"/g, '""') + '"' : s }
+function toCsv(rows) {
+  const arr = Array.isArray(rows) ? rows : [rows]
+  if (!arr.length) return ''
+  if (typeof arr[0] !== 'object' || Array.isArray(arr[0])) return arr.join('\n')
+  const keys = Object.keys(arr[0])
+  return [keys.join(','), ...arr.map(r => keys.map(k => csvCell(r[k])).join(','))].join('\n')
+}
+
+/** List every country pack, with its ISO code. */
+export function listCountries() {
+  const codes = listPacks()
+  const lines = codes.map(c => `${c.toLowerCase()}`)
+  return text(`${codes.length} countries available (use the lower-case code as a spec prefix, e.g. "ke.person"):\n\n${lines.join(', ')}`)
+}
+
+/** Describe a country's fields and preset scenarios. */
+export function describeCountry({ country }) {
+  const code = String(country || '').toLowerCase()
+  let fields, presets
+  try {
+    fields = listFields(code)
+    presets = listPresets(code)
+  } catch (e) {
+    return fail(e.message)
+  }
+  const fieldLines = fields.map(f => `  ${f.key.padEnd(16)} ${f.label}`).join('\n')
+  const presetLines = presets.length
+    ? '\n\nPreset scenarios (use spec "' + code + '.preset:<key>"):\n' + presets.map(p => `  ${p.key.padEnd(16)} ${p.name}`).join('\n')
+    : ''
+  return text(`Fields for ${code} (spec "${code}.<field>", or "${code}.person" for a full record):\n${fieldLines}${presetLines}`)
+}
+
+/**
+ * Generate synthetic data.
+ *   spec:   "<country>.<selector>" — selector is a field key, "person", or "preset:<key>"
+ *   count:  number of rows (omit or 1 for a single value/record)
+ *   fields: array of field keys, or "all" (applies to person records)
+ *   seed:   string for reproducible output
+ *   format: "json" (default) or "csv"
+ */
+export function generateData({ spec, count, fields, seed, format }) {
+  if (!spec || typeof spec !== 'string') return fail('`spec` is required, e.g. "ke.person" or "de.iban".')
+  const settings = {}
+  if (seed != null && seed !== '') settings.seed = String(seed)
+  if (fields != null) settings.fields = fields === 'all' ? 'all' : (Array.isArray(fields) ? fields : String(fields).split(',').map(s => s.trim()).filter(Boolean))
+
+  let data
+  try {
+    const n = Number(count) || 0
+    data = n > 1 ? generateMany(spec, n, settings) : generate(spec, settings)
+  } catch (e) {
+    return fail(e.message)
+  }
+
+  if (format === 'csv') return text(toCsv(data))
+  return text(typeof data === 'string' ? data : JSON.stringify(data, null, 2))
+}