katyayani-core-mcp 1.0.0

package/README.md

@@ -0,0 +1,56 @@
+# katyayani-core-mcp
+
+MCP server for **Katyayani Core** (Customer Engagement Platform). Add it to Claude / Cursor / any MCP
+client and ask anything about the platform — live data **and** how the SDKs work.
+
+## What you can ask
+
+- **Live data** (needs a token): "How many installs from google-play last 30 days?", "Top referrers",
+  "Revenue by source", "Show the acquisition funnel", "Find user 6261414316".
+- **How-to / docs** (no token needed): "How do I add referral sharing?", "How to set user attributes?",
+  "What does trackAttribution do?", "How to install the Flutter SDK?", "Does the RN SDK auto-ask push permission?"
+
+## Tools
+
+| Tool | Purpose |
+|------|---------|
+| `kc_docs` | Platform + SDK knowledge (install, identify/attributes, events, attribution, referral, push). Works with **no token**. |
+| `kc_get` | Read live dashboard data (users, attribution, revenue, referrals, funnels…). Needs `KC_TOKEN`. |
+| `kc_action` | Write actions (create smart link, send message…). Needs `KC_TOKEN`. |
+
+## Install (Claude Code)
+
+```bash
+claude mcp add katyayani-core \
+  -e KC_TOKEN=<shared-token> \
+  -e KC_TENANT_ID=<project-tenant-id> \
+  -- npx -y katyayani-core-mcp
+```
+
+- **`KC_TOKEN`** — the shared access token (ask whoever gave you this MCP). Omit it and only `kc_docs` works.
+- **`KC_TENANT_ID`** *(optional)* — scopes all data to one project. Omit → the API's default project.
+- **`KC_API_BASE`** *(optional)* — defaults to `https://8.231.80.238.nip.io`.
+
+### Cursor / other clients (`mcp.json`)
+
+```json
+{
+  "mcpServers": {
+    "katyayani-core": {
+      "command": "npx",
+      "args": ["-y", "katyayani-core-mcp"],
+      "env": { "KC_TOKEN": "<shared-token>", "KC_TENANT_ID": "<tenant-id>" }
+    }
+  }
+}
+```
+
+## Security
+
+`KC_TOKEN` is a full-access dashboard token — share it only with people you trust. It is **never** baked
+into this package; it is read from your MCP config at runtime. `kc_docs` needs no token, so you can share
+the docs experience openly.
+
+## License
+
+MIT

package/dist/api.js

@@ -0,0 +1,66 @@
+// Thin authenticated HTTP layer for the Katyayani Core dashboard API.
+// Auth = a single shared token sent as `Authorization: Bearer <token>`.
+// The default is the platform's static dashboard key; override via KC_TOKEN.
+// KC_TENANT_ID (optional) scopes every call to one project via the x-tenant-id header.
+export const API_BASE = (process.env.KC_API_BASE || 'https://8.231.80.238.nip.io').replace(/\/$/, '');
+// Shared access token — provided by whoever shares this MCP, via the KC_TOKEN env.
+// Intentionally NOT hardcoded so the secret never ships inside the published package.
+const TOKEN = process.env.KC_TOKEN || '';
+export const TENANT_ID = process.env.KC_TENANT_ID || '';
+const NO_TOKEN_MSG = 'No access token set. Live data (kc_get / kc_action) needs the shared KC_TOKEN env var — ' +
+    'ask whoever shared this MCP for the token, then set KC_TOKEN in your MCP config. ' +
+    'Docs (kc_docs) work without a token.';
+function headers(extra = {}) {
+    const h = { authorization: `Bearer ${TOKEN}`, ...extra };
+    if (TENANT_ID)
+        h['x-tenant-id'] = TENANT_ID;
+    return h;
+}
+function normalizePath(path) {
+    let p = path.trim();
+    if (!p.startsWith('/'))
+        p = '/' + p;
+    // Be forgiving: allow callers to pass "attribution/overview" or "/v1/..." etc.
+    if (!p.startsWith('/v1/') && !p.startsWith('/health') && p !== '/') {
+        p = '/v1' + p;
+    }
+    return p;
+}
+async function parse(res) {
+    const text = await res.text();
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return { _status: res.status, _nonJson: text.slice(0, 2000) };
+    }
+}
+export async function apiGet(path, params) {
+    if (!TOKEN)
+        return { error: NO_TOKEN_MSG };
+    const p = normalizePath(path);
+    let qs = '';
+    if (params && Object.keys(params).length) {
+        const usp = new URLSearchParams();
+        for (const [k, v] of Object.entries(params)) {
+            if (v !== undefined && v !== null && v !== '')
+                usp.set(k, String(v));
+        }
+        const s = usp.toString();
+        if (s)
+            qs = '?' + s;
+    }
+    const res = await fetch(`${API_BASE}${p}${qs}`, { headers: headers() });
+    return parse(res);
+}
+export async function apiSend(method, path, body) {
+    if (!TOKEN)
+        return { error: NO_TOKEN_MSG };
+    const p = normalizePath(path);
+    const res = await fetch(`${API_BASE}${p}`, {
+        method: method.toUpperCase(),
+        headers: headers({ 'content-type': 'application/json' }),
+        body: body != null ? JSON.stringify(body) : undefined,
+    });
+    return parse(res);
+}

package/dist/docs.js

@@ -0,0 +1,180 @@
+// Bundled Katyayani Core knowledge base. `kc_docs` returns the whole thing (or
+// the sections matching a topic) so anyone can ask how the platform / SDKs work.
+const SECTIONS = [
+    {
+        title: 'Overview — what Katyayani Core is',
+        keywords: ['overview', 'what', 'platform', 'intro', 'about', 'architecture'],
+        body: `Katyayani Core is a multi-tenant Customer Engagement Platform (Netcore / Linkrunner-style MMP).
+It ingests events from client SDKs (Flutter, React Native, Web), stitches user identities, tracks
+install attribution + revenue, sends push notifications, and shows everything in a dashboard.
+
+- API base URL: https://8.231.80.238.nip.io
+- Dashboard: same host (Next.js). Events/analytics, Attribution, Users, Push, Segments, Workflows.
+- Each project = a "tenant"/app with its own SDK API key (nc_live_...). A key maps to a tenant.
+- Data stores: Postgres (users, links, config), ClickHouse (events, attribution funnel, revenue).`,
+    },
+    {
+        title: 'SDK install — Flutter, React Native, Web',
+        keywords: ['install', 'setup', 'sdk', 'init', 'flutter', 'react native', 'rn', 'web', 'add'],
+        body: `All three SDKs talk to the same backend and share the same core API (init, identify, track,
+attribution, capturePayment, referral).
+
+FLUTTER (package "katyayani_core" on pub.dev, latest 1.10.0):
+  dependencies: katyayani_core: ^1.10.0
+  await KatyayaniCore.init(
+    siteId: 'nc_live_...',                 // your SDK API key
+    apiBase: 'https://8.231.80.238.nip.io',
+    enablePush: false,                     // set true ONLY if Firebase is configured (see Push section)
+  );
+
+REACT NATIVE (package "katyayani-core-react-native" on npm, latest 1.3.0):
+  npm i katyayani-core-react-native
+  await KatyayaniCore.init({ siteId: 'nc_live_...', apiBase: 'https://8.231.80.238.nip.io', enablePush: true });
+
+WEB (self-hosted script, global nc(...)):
+  <script src="https://8.231.80.238.nip.io/nc.min.js"></script>
+  nc('init', { siteId: 'nc_live_...', apiBase: 'https://8.231.80.238.nip.io' });`,
+    },
+    {
+        title: 'Identify & user attributes (traits)',
+        keywords: ['identify', 'user', 'attribute', 'attributes', 'traits', 'profile', 'phone', 'email', 'set user'],
+        body: `Set user attributes with identify() — there is NO separate setUserAttributes method.
+
+  KatyayaniCore.identify('+916261414316', traits: {
+    'phone': '+916261414316',   // recognized → phone column (needed for Users search)
+    'email': 'ram@x.com',       // recognized → email column
+    'name': 'Ram Kumar',        // auto-split into firstName/lastName
+    'city': 'Indore',           // any other key → customAttributes (JSON)
+    'plan': 'premium',
+  });
+
+Recognized keys → dedicated columns: phone, email, name, firstName, lastName, $timezone, $locale.
+Everything else → customAttributes.
+
+MERGE BEHAVIOR (important):
+- Standard fields (phone/email/name...) are PATCHED — fields you don't send stay unchanged.
+- customAttributes are REPLACED as a whole IF you send any custom key. Sending {plan:'gold'} alone
+  wipes other custom attributes. To update one custom attribute safely, resend all custom attributes,
+  OR ask the platform team to enable server-side jsonb merge.
+- Sending only standard fields (no custom keys) leaves customAttributes untouched.
+
+You MUST call identify() to create a profile — init() alone keeps the user anonymous.
+Use a stable, readable userId (e.g. '+916261414316'), not a random UUID.`,
+    },
+    {
+        title: 'Events & ecommerce tracking',
+        keywords: ['event', 'track', 'ecommerce', 'purchase', 'screen', 'analytics', 'ga4'],
+        body: `Track custom events and GA4-aligned ecommerce events.
+
+  KatyayaniCore.track('button_clicked', properties: {'screen': 'home'});
+  KatyayaniCore.screenView('ProductPage');
+
+Ecommerce convenience methods (GA4 payload {currency, value, transaction_id, items:[...]}):
+  viewItem, addToCart, removeFromCart, viewCart, beginCheckout, addPaymentInfo, purchase, refund.
+  e.g. KatyayaniCore.purchase({'currency':'INR','value':1499,'transaction_id':'ORD1','items':[...]});
+
+track() = product analytics (Analytics/Events pages). For revenue attribution use capturePayment().`,
+    },
+    {
+        title: 'Attribution & sources (Meta / Google / organic / referral)',
+        keywords: ['attribution', 'source', 'meta', 'google', 'ads', 'organic', 'utm', 'install', 'trackattribution', 'funnel', 'campaign', 'smart link'],
+        body: `WHICH source a user came from (meta / google / organic / referral) is detected AUTOMATICALLY at
+install time (resolveInstall runs on init). You never pass the source manually. It is derived from:
+  1. A Katyayani Core smart link click (/l/<code>) — the link's configured source wins.
+  2. Play Store install referrer UTM (utm_source=google, etc.).
+  3. Click→install fingerprint match (iOS / no referrer).
+  4. Nothing matched → 'organic'.
+
+To make Meta/Google show up (not 'organic'), drive installs through a KC SMART LINK per channel
+(Dashboard → Attribution → Links, source=meta/google) OR a Play Store URL tagged with utm_source.
+
+FUNNEL milestones are MANUAL — the SDK can't know when "signup" happens:
+  KatyayaniCore.trackAttribution('signup');   // ties this conversion to the user's acquired source
+  KatyayaniCore.capturePayment(1499, orderId: 'ORD1');  // ties revenue to source
+
+Funnel: click → install → signup (trackAttribution) → purchase (capturePayment). The built-in funnel
+only counts type 'signup' as the signup step; other trackAttribution types are stored as raw events.
+
+Manual vs auto:
+  AUTO  → source detection, referral tracking, install/click counts.
+  MANUAL→ trackAttribution('signup'), capturePayment(amount), putting a KC smart link in your ads.`,
+    },
+    {
+        title: 'Referral sharing (referral attribution)',
+        keywords: ['referral', 'refer', 'share', 'generatereferrallink', 'onreferral', 'confirmreferral', 'referrer', 'referee', 'invite'],
+        body: `Referral flow (app shares a link → new user installs → code auto-links → backend tracks who
+referred whom). Available in all 3 SDKs (Flutter 1.10.0, RN 1.3.0, Web).
+
+1) SHARE side (referrer):
+   final url = await KatyayaniCore.generateReferralLink(
+     myReferralCode,                       // your app's own code (app-provided)
+     referrerId: currentUserId,            // sharer's userId
+     deepLinkPath: '/referral',
+     androidStoreUrl: 'https://play.google.com/store/apps/details?id=com.mymali', // REQUIRED
+   );
+   Share.share('Join with my code: $url');
+
+2) INSTALL side (new user) — auto:
+   KatyayaniCore.onReferral((code, params) {
+     referralField.text = code;            // auto-fill; params['referrerId'] = who referred
+   });
+
+3) After signup (authoritative):
+   KatyayaniCore.confirmReferral(code, referrerId: params['referrerId']);
+
+The SDK DELIVERS the code + referrerId to your app via onReferral; YOUR app decides which field to
+fill and how to reward. Reward crediting lives in your backend. Backend records referrer↔referee in
+the referrals table; report at GET /v1/attribution/referrals.
+androidStoreUrl (Play details URL) must be passed once so the install-referrer flow works.
+
+Web commands: nc('referral.generate', opts, cb); nc('referral.on', cb); nc('referral.confirm', code, opts); nc('referral.getCode', cb).`,
+    },
+    {
+        title: 'Push notifications',
+        keywords: ['push', 'notification', 'fcm', 'firebase', 'permission', 'enablepush', 'sticky', 'timer'],
+        body: `Push uses Firebase (FCM). enablePush defaults to TRUE in the Flutter SDK.
+
+- No Firebase in the project? Set enablePush: false — otherwise init() can throw (no default Firebase
+  app) and the WHOLE SDK fails to initialize (events/attribution/referral stop too).
+- With enablePush:true the SDK registers the FCM token on startup WITHOUT asking permission
+  (getToken works without display permission). It does NOT auto-request notification permission.
+- To actually show notifications, call KatyayaniCore.requestPushPermission() at a good moment
+  (needed for Android 13+ POST_NOTIFICATIONS and iOS). Add POST_NOTIFICATIONS to AndroidManifest.
+- Rich push (sticky / timer / custom sound) is Flutter-only. RN has FCM topics + host-rendered nudges.
+- Per-project FCM service account is configured in Dashboard → Settings → App Management.`,
+    },
+    {
+        title: 'Dashboard data & API endpoints',
+        keywords: ['dashboard', 'api', 'endpoint', 'data', 'report', 'query', 'revenue', 'users', 'segments', 'workflows'],
+        body: `Read data via kc_get (GET) and mutate via kc_action (POST/PATCH/DELETE). Common paths:
+
+Attribution:  /v1/attribution/overview?days=30   (per-source clicks/installs/revenue/ROAS)
+              /v1/attribution/funnel?days=30
+              /v1/attribution/timeseries?days=30
+              /v1/attribution/referrals?limit=100  (top referrers)
+              /v1/attribution/links                (smart links)
+Users:        /v1/users?page=1&limit=20&search=... ; /v1/users/:id ; /v1/users/:id/activity
+Analytics:    /v1/analytics/overview?days=30 ; /v1/analytics/revenue ; /v1/analytics/events/summary
+              /v1/analytics/retention ; /v1/analytics/rfm ; /v1/analytics/geo ; /v1/analytics/devices
+Apps/config:  /v1/apps ; /v1/settings/api-keys ; /v1/segments ; /v1/workflows ; /v1/nudges
+Actions:      POST /v1/attribution/links (create smart link),
+              POST /v1/attribution/referral/generate (needs SDK key, not dashboard token),
+              POST /v1/transactional/email|sms|whatsapp, POST /v1/segments.
+
+Auth is a single shared Bearer token; KC_TENANT_ID scopes to one project.`,
+    },
+];
+const TOC = SECTIONS.map((s, i) => `  ${i + 1}. ${s.title}`).join('\n');
+export function getDocs(topic) {
+    const header = `# Katyayani Core — Knowledge Base\n\nSections:\n${TOC}\n\n(Call kc_docs with a topic keyword to narrow, or no topic for everything.)\n\n`;
+    if (topic && topic.trim()) {
+        const q = topic.toLowerCase();
+        const matched = SECTIONS.filter((s) => s.title.toLowerCase().includes(q) ||
+            s.keywords.some((k) => q.includes(k) || k.includes(q)));
+        if (matched.length) {
+            return matched.map((s) => `## ${s.title}\n\n${s.body}`).join('\n\n---\n\n');
+        }
+        // No match → fall through to full docs so the caller still gets an answer.
+    }
+    return header + SECTIONS.map((s) => `## ${s.title}\n\n${s.body}`).join('\n\n---\n\n');
+}

package/dist/index.js

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { apiGet, apiSend, API_BASE, TENANT_ID } from './api.js';
+import { getDocs } from './docs.js';
+const ENDPOINT_CATALOG = `
+Common GET paths (pass as "path", optional "params"):
+  Attribution:
+    /v1/attribution/overview     params: {days}   → per-source clicks/installs/users/orders/revenue/ROAS
+    /v1/attribution/funnel       params: {days}   → click→install→signup→purchase counts
+    /v1/attribution/timeseries   params: {days}   → daily revenue/installs by source
+    /v1/attribution/referrals    params: {limit}  → top referrers + totals (who referred whom)
+    /v1/attribution/links                          → all smart links
+    /v1/attribution/links/:id/stats params:{days}
+  Users:
+    /v1/users                    params: {page,limit,search}
+    /v1/users/:id                                  → single profile (traits, customAttributes)
+    /v1/users/:id/activity                         → recent events
+  Analytics:
+    /v1/analytics/overview       params: {days}
+    /v1/analytics/revenue        params: {days}
+    /v1/analytics/events/summary params: {days}
+    /v1/analytics/retention | /rfm | /geo | /devices | /realtime | /fatigue
+  Config:
+    /v1/apps                                        → projects + SDK keys
+    /v1/segments | /v1/workflows | /v1/nudges | /v1/settings/api-keys
+`;
+const tools = [
+    {
+        name: 'kc_docs',
+        description: 'Explain how Katyayani Core (the Customer Engagement Platform) and its SDKs work. Covers: platform overview, SDK install (Flutter/React Native/Web), identify & user attributes, events/ecommerce, attribution & sources (Meta/Google/organic/referral), the referral system, push notifications, and the dashboard/API. Use for any "how do I / what is / how does X work" question. Pass an optional topic keyword to focus.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                topic: {
+                    type: 'string',
+                    description: 'Optional keyword to focus the docs, e.g. "referral", "attribution", "user attributes", "push", "install", "events". Omit to get everything.',
+                },
+            },
+        },
+    },
+    {
+        name: 'kc_get',
+        description: 'Read LIVE data from the Katyayani Core dashboard API (GET). Use for any question about real numbers: users, events, attribution by source, revenue/ROAS, funnels, referrals, segments, workflows, etc. Provide the API "path" and optional "params". ' +
+            ENDPOINT_CATALOG,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: {
+                    type: 'string',
+                    description: 'API path, e.g. "/v1/attribution/overview" or "/v1/users". "/v1" is added if you omit it.',
+                },
+                params: {
+                    type: 'object',
+                    description: 'Optional query params, e.g. {"days": 30} or {"search": "6261", "limit": 20}.',
+                    additionalProperties: true,
+                },
+            },
+            required: ['path'],
+        },
+    },
+    {
+        name: 'kc_action',
+        description: 'Perform a WRITE action on Katyayani Core (POST/PATCH/DELETE) — e.g. create a smart link (POST /v1/attribution/links), create a segment, send a transactional message. This MUTATES data; use only when the user explicitly asks to create/update/send something. Prefer kc_get for reads.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                method: { type: 'string', enum: ['POST', 'PATCH', 'DELETE'], description: 'HTTP method (default POST).' },
+                path: { type: 'string', description: 'API path, e.g. "/v1/attribution/links".' },
+                body: { type: 'object', description: 'JSON body for the request.', additionalProperties: true },
+            },
+            required: ['path'],
+        },
+    },
+];
+const server = new Server({ name: 'katyayani-core', version: '1.0.0' }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const { name } = req.params;
+    const args = (req.params.arguments || {});
+    try {
+        if (name === 'kc_docs') {
+            return { content: [{ type: 'text', text: getDocs(args.topic) }] };
+        }
+        if (name === 'kc_get') {
+            if (!args.path)
+                throw new Error('path is required');
+            const data = await apiGet(String(args.path), args.params);
+            return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        }
+        if (name === 'kc_action') {
+            if (!args.path)
+                throw new Error('path is required');
+            const data = await apiSend(String(args.method || 'POST'), String(args.path), args.body);
+            return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        }
+        return { content: [{ type: 'text', text: `Unknown tool: ${name}` }], isError: true };
+    }
+    catch (e) {
+        return { content: [{ type: 'text', text: `Error: ${e?.message || String(e)}` }], isError: true };
+    }
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`katyayani-core MCP running → ${API_BASE}${TENANT_ID ? ` (tenant ${TENANT_ID})` : ''}`);
+}
+main().catch((e) => {
+    console.error('katyayani-core MCP failed to start:', e);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "katyayani-core-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for Katyayani Core (Customer Engagement Platform). Ask anything about your CEP — users, events, attribution (Meta/Google/organic/referral), revenue/ROAS, referrals, funnels — plus full SDK & platform how-to docs.",
+  "type": "module",
+  "bin": {
+    "katyayani-core-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "katyayani-core",
+    "analytics",
+    "attribution",
+    "claude"
+  ],
+  "author": "Katyayani Organics",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}