Kapruka Mcp

kapruka-mcp — MCP Server & TypeScript SDK for Kapruka.com

> MCP (Model Context Protocol) server and TypeScript SDK for building AI-powered shopping agents on Kapruka.com — Sri Lanka's largest e-commerce platform. Works with Claude Desktop, Cursor, VS Code Copilot, and any MCP-compatible AI client.

[](https://www.npmjs.com/package/kapruka-mcp) [](https://www.npmjs.com/package/kapruka-mcp) [](https://www.typescriptlang.org/) [](LICENSE) [](https://github.com/kapruka-mcp/kapruka-mcp/actions) [](https://modelcontextprotocol.io)

A Model Context Protocol (MCP) server and TypeScript SDK for building conversational commerce applications, AI shopping agents, and chatbot integrations on top of Kapruka.com — Sri Lanka's largest e-commerce platform.

Built for developers entering the Kapruka Agent Challenge 2026 and anyone building AI-powered e-commerce agents for the Sri Lankan market.

What is MCP?

Model Context Protocol (MCP) is an open standard that lets AI assistants like Claude, Cursor, and VS Code Copilot connect to external tools and data sources. This package implements an MCP server that exposes Kapruka.com's product catalog, shopping cart, delivery, and order management as 15 tools any AI agent can use.

---

Why use this instead of the raw MCP URL?

| Feature | Raw mcp.kapruka.com | kapruka-mcp SDK | |---|---|---| | MCP protocol compliance | Non-standard params nesting | Flat args -- works with all MCP clients | | TypeScript types | -- | Full types for all 15 tools | | Offline / mock mode | -- | 136-product catalog, no internet needed | | Live mode | 7 tools | All 15 tools (7 server + 8 composed) | | Response format | Markdown text | Structured JSON | | Cart persistence | Stateless | Memory or SQLite | | Response caching | -- | 30-minute TTL cache | | Rate limit tracking | -- | 60 req/min, 30 orders/hr | | Event hooks | -- | onToolCall, onError | | Perishable delivery logic | -- | Cakes/flowers blocked to remote cities | | REST API | -- | HTTP endpoints with session management | | React hooks | -- | useKaprukaSearch, useCart, useCheckout | | npm install | -- | One command |

> MCP Protocol Fix: The official Kapruka MCP server uses non-standard parameter nesting ({ params: { q: "cake" } } instead of flat { q: "cake" }). This breaks standard MCP clients like Claude Desktop and Cursor. kapruka-mcp fixes this transparently so all 7 official tools work out of the box with any MCP-compatible AI agent.

Live mode compatibility

The SDK works against the official Kapruka MCP server (mcp.kapruka.com). The server returns markdown -- the SDK parses it into structured JSON automatically. All 7 official tools work, plus 8 extra tools built on top:

| Official tools (7) | Extra tools (8) -- composed from official | |---|---| | search_products | get_alternatives (uses search + scoring) | | get_product | validate_shipping (uses listdeliverycities) | | list_categories | get_recommendations (uses search by category) | | list_delivery_cities | convert_currency (Frankfurter API) | | check_delivery | add_to_cart (local storage) | | create_order | get_cart (local storage) | | track_order | get_analytics (local storage) | | | clear_cart (local storage) |

---

Installation

npm install kapruka-mcp

For persistent SQLite cart storage (optional):

npm install kapruka-mcp better-sqlite3

For React hooks (frontend projects):

npm install kapruka-mcp react

> Requires: Node.js 18+, TypeScript 5.x

---

Quick Start -- 30 seconds

Option A: Direct SDK (call Kapruka's live MCP server)

import { KaprukaSDK } from 'kapruka-mcp';

const sdk = new KaprukaSDK();

// Search products
const results = await sdk.searchProducts('birthday cake', 'cakes');
console.log(results.products[0].name); // "Java Lounge Classic Ribbon Cake"

// Get full product detail
const product = await sdk.getProduct('KAP-CAKE-001');

// Check delivery to Kandy
const delivery = await sdk.checkDelivery('KAN', 'KAP-CAKE-001');

// Add to cart
await sdk.addToCart('KAP-CAKE-001', product.name, product.price, 1);

// Create checkout link
const order = await sdk.createOrder({
  cart: [{ product_id: 'KAP-CAKE-001', quantity: 1 }],
  recipient: {
    name: 'Amara Perera',
    phone: '0771234567',
    address: '42 Galle Road, Colombo 03',
    city: 'COL',
  },
  delivery: { date: '2026-06-05' },
  sender: { name: 'Rithik', phone: '0779876543' },
});
console.log(order.checkout_url); // "https://www.kapruka.com/checkout/pay/..."

Option B: Local MCP Server (for Claude Desktop, Cursor, or your AI agent)

import { KaprukaLocal } from 'kapruka-mcp/local';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const local = new KaprukaLocal({
  mock: true, // offline dev with 136 products
  events: {
    onToolCall: (tool, args) => console.error(`[${tool}]`, args),
    onError: (tool, err)  => console.error(`[ERROR:${tool}]`, err.message),
  },
});

const transport = new StdioServerTransport();
await local.getServer().connect(transport);

Option C: With SQLite persistence (cart survives process restarts)

import { KaprukaLocal } from 'kapruka-mcp/local';
import { SqliteStorage } from 'kapruka-mcp/storage';

const local = new KaprukaLocal({
  mock: false, // use the live Kapruka MCP server
  storage: new SqliteStorage('./kapruka-session.db'),
});

Option D: REST API server

# Mock mode (offline)
npx kapruka-mcp --mock --rest --port 3001

# Live mode (real Kapruka catalog)
npx kapruka-mcp --rest --port 3001

import { createRestServer } from 'kapruka-mcp/rest';

const server = createRestServer({ port: 3001, mock: true });
await server.start();
console.log(`REST API running at ${server.url()}`);

Option E: React hooks

import { KaprukaProvider, useKaprukaSearch, useCart, useCheckout } from 'kapruka-mcp/react';

function App() {
  return (
    
      
    
  );
}

function ShoppingPage() {
  const { results, search } = useKaprukaSearch();
  const { items, total, addItem } = useCart();
  const { order, createOrder } = useCheckout(items);
  // ...
}

---

Claude Desktop Integration

Add this to your claude_desktop_config.json:

Using the npm CLI (recommended):

{
  "mcpServers": {
    "kapruka": {
      "command": "npx",
      "args": ["-y", "kapruka-mcp", "--mock"]
    }
  }
}

Or point directly at Kapruka's live server:

{
  "mcpServers": {
    "kapruka": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.kapruka.com/mcp"]
    }
  }
}

> Config file locations: > - macOS: ~/Library/Application Support/Claude/claude_desktop_config.json > - Windows: %APPDATA%\Claude\claude_desktop_config.json

---

REST API Endpoints

Every endpoint returns { success: true, data: ..., sessionId: "..." }.

| Method | Path | Description | |--------|------|-------------| | POST | /api/search | Search products | | POST | /api/product | Get product details | | POST | /api/alternatives | Find similar products | | GET | /api/categories | List categories | | GET | /api/cities | List delivery cities | | POST | /api/delivery/check | Check delivery availability | | POST | /api/shipping/validate | Validate shipping address | | POST | /api/cart/add | Add item to cart | | GET | /api/cart | View cart | | DELETE | /api/cart | Clear cart | | POST | /api/order/create | Create checkout order | | POST | /api/order/track | Track order status | | POST | /api/currency/convert | Convert currency | | POST | /api/recommendations | Get recommendations | | POST | /api/analytics | View analytics | | POST | /api/tool | Universal tool endpoint | | GET | /api/tools | List all tools | | GET | /api/health | Health check |

---

Available Tools

All 15 tools match or extend Kapruka's official capabilities. The local server adds caching, rate limiting, and stateful persistence.

| Tool | Category | Description | Memory | |------|----------|-------------|--------| | kapruka_search_products | Search | Multi-category search with rank-optimized results | Yes | | kapruka_get_product | Detail | Detailed product info with visual descriptions | Yes | | kapruka_get_alternatives | AI Logic | Find similar products to avoid "nothing found" dead ends | -- | | kapruka_get_recommendations | Upsell | Suggests "Go well with" items based on cart | Yes | | kapruka_add_to_cart | Cart | Persists item to local SQLite cart | Yes | | kapruka_get_cart | Cart | Retrieves currently saved items | Yes | | kapruka_clear_cart | Cart | Clears all items from session cart | -- | | kapruka_list_categories | Reference | Browse 12+ premium categories | -- | | kapruka_list_delivery_cities | Reference | Get fees for 16+ Sri Lankan cities | -- | | kapruka_check_delivery | Logistics | Perishable-aware delivery calculations | -- | | kapruka_validate_shipping | Validation | Validate Sri Lankan phone, city, and address before checkout | -- | | kapruka_convert_currency | Localization | Convert LKR to USD, AED, EUR, GBP, INR | -- | | kapruka_create_order | Checkout | Generates 60-minute price-locked pay links | -- | | kapruka_track_order | Status | Monitors order status progression | Yes | | kapruka_get_analytics | Dev Only | See which products are trending in your AI session | Yes |

Robust Error Handling & Reliability

• Connectivity Guard: Automatically detects if the Kapruka server is down or unreachable and provides a descriptive error message instead of generic failures.
• Spec-Compliant: Perfectly aligned with the official Kapruka MCP specification for 100% compatibility in Live Mode.
• Data Validation: Built-in detection for application-level errors and invalid JSON, with suggested fixes for the AI.
• Progressive Caching: In live mode, getAlternatives fires 2-4 parallel search queries, deduplicates results, and caches them in storage with a 30-minute TTL.
• REST Body Limits: 1MB default body size limit prevents memory exhaustion.
• Session Management: LRU eviction, 30-minute timeout, automatic cleanup.

Developer Analytics & Memory

Every tool call, view, and cart action is recorded in storage.

• Use kapruka_get_analytics to see what your users are looking at.
• AI uses this history to provide a personalized shopping experience.

Delivery Rules

The local server enforces Kapruka's real delivery constraints:

• Perishables (cakes, flowers, fruits): cannot be delivered to cities with 3+ day lead times (Jaffna, Trincomalee, Batticaloa, Vavuniya).
• High-value items (electronics, appliances): +1 extra day for security handling.
• Colombo (COL): always free delivery, same day.

---

Mock Catalog

The package ships with 136 realistic products across all 12 categories for offline development -- no internet required.

| Category | Products | Highlights | |----------|----------|-----------| | Flowers | 16 | Red roses, orchids, rose heart boxes | | Cakes | 16 | Java Lounge, Hilton, Cinnamon Grand | | Electronics | 14 | iPhone 15 Pro, MacBook Air M2, DJI Mini 3 | | Gifts | 10 | Hampers, corporate boxes, personalised gifts | | Fashion | 8 | G-Shock, Nike Air Max, Kanjeevaram silk | | Grocery | 14 | Dilmah tea, Ceylon spices, Milo | | Appliances | 8 | Dyson, Breville, Philips Air Fryer | | Beauty | 10 | Chanel, Dyson Airwrap, The Ordinary | | Books | 10 | Atomic Habits, Sapiens, local titles | | Fruits | 8 | King coconut, Nuwara Eliya strawberries | | Beverages | 10 | Ferrero Rocher, Lindt, Mlesna tea | | Toys | 12 | LEGO, Barbie, RC Monster Truck |

---

TypeScript Types

All types are exported from the root package:

import type {
  Product,
  Category,
  DeliveryCity,
  DeliveryCheck,
  Order,
  OrderItem,
  SearchResult,
  CartItem,
  CreateOrderRequest,
  OrderRecipient,
  OrderDelivery,
  OrderSender,
  ShippingAddress,
  ShippingValidation,
  KaprukaSDKConfig,
  KaprukaLocalConfig,
} from 'kapruka-mcp';

---

Using with AI Frameworks

Vercel AI SDK

import { KaprukaSDK } from 'kapruka-mcp';
import { tool } from 'ai';
import { z } from 'zod';

const sdk = new KaprukaSDK();

const tools = {
  searchProducts: tool({
    description: 'Search Kapruka products',
    parameters: z.object({
      q: z.string().describe('Search keyword'),
      category: z.string().optional(),
    }),
    execute: async ({ q, category }) => sdk.searchProducts(q, category),
  }),
  getProduct: tool({
    description: 'Get full product details',
    parameters: z.object({ product_id: z.string().describe('Product SKU') }),
    execute: async ({ product_id }) => sdk.getProduct(product_id),
  }),
};

LangChain / LangGraph

import { KaprukaSDK } from 'kapruka-mcp';
import { DynamicTool } from 'langchain/tools';

const sdk = new KaprukaSDK();

const searchTool = new DynamicTool({
  name: 'kapruka_search',
  description: 'Search Kapruka.com for products. Input: JSON string with q (keyword) and optional category.',
  func: async (input: string) => {
    const { q, category } = JSON.parse(input);
    const result = await sdk.searchProducts(q, category);
    return JSON.stringify(result);
  },
});

Google Gemini (function calling)

import { KaprukaSDK } from 'kapruka-mcp';

const sdk = new KaprukaSDK();

const functionDeclarations = [
  {
    name: 'kapruka_search_products',
    description: 'Search Kapruka product catalog',
    parameters: {
      type: 'OBJECT',
      properties: {
        q:        { type: 'STRING', description: 'Search keyword' },
        category: { type: 'STRING', description: 'Optional category filter' },
      },
      required: ['q'],
    },
  },
];

async function handleFunctionCall(name: string, args: Record) {
  if (name === 'kapruka_search_products') {
    return sdk.searchProducts(args.q, args.category);
  }
}

---

Event Hooks

Log every tool call and error for observability:

const local = new KaprukaLocal({
  mock: true,
  events: {
    onToolCall: (tool, args) => {
      console.log(JSON.stringify({ event: 'tool_call', tool, args, ts: Date.now() }));
    },
    onError: (tool, error) => {
      console.error(JSON.stringify({ event: 'tool_error', tool, message: error.message, ts: Date.now() }));
    },
  },
});

---

Storage Options

In-Memory (default -- no dependencies)

import { KaprukaLocal, MemoryStorage } from 'kapruka-mcp/local';

const local = new KaprukaLocal({ storage: new MemoryStorage() });

SQLite (optional -- cart persists across restarts)

npm install better-sqlite3

import { KaprukaLocal } from 'kapruka-mcp/local';
import { SqliteStorage } from 'kapruka-mcp/storage';

const local = new KaprukaLocal({
  storage: new SqliteStorage('./session.db', 'kapruka_cart'),
});

Auto-detect storage

import { createStorage, createStorageAsync } from 'kapruka-mcp/storage';

// Sync (CJS)
const storage = createStorage({ type: 'memory' });
const storage = createStorage({ type: 'sqlite', path: './data.db' });

// Async (ESM)
const storage = await createStorageAsync({ type: 'sqlite', path: './data.db' });

---

CLI Usage

# Mock mode (offline, no API key needed)
npx kapruka-mcp --mock

# Live mode (calls mcp.kapruka.com)
npx kapruka-mcp

# REST API server
npx kapruka-mcp --mock --rest --port 3001

---

Package Exports

| Import path | What you get | |---|---| | kapruka-mcp | KaprukaSDK, MemoryStorage, SqliteStorage, all TypeScript types | | kapruka-mcp/local | KaprukaLocal MCP server, KaprukaEvents, mock helpers | | kapruka-mcp/storage | `MemoryStorag

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: kapruka-mcp
• Source: kapruka-mcp/kapruka-mcp
• License: MIT
• Homepage: https://www.kapruka.com/contactUs/agentChallenge.html

Install and usage instructions live in the source repository linked above.