Caramelo

Multi-channel chatbot for DulceGestion - a pastry shop management SaaS.

What it does

Answers user questions about how to use the app (RAG-powered from documentation)
Queries live business data (orders, stock, customers) via tool calling
Works on Telegram, Web Widget (embeddable), and WhatsApp (Twilio)
Exposes an MCP server for use with Claude Desktop/Code

Architecture

Channels (in/out)        Brain                  Data
+----------------+    +----------------+    +------------------+
| Telegram       |--->|                |--->| RAG (docs)       |
| Web Widget     |--->|   Bot Engine   |--->| MCP Tools        |
| WhatsApp       |--->|                |--->| Claude LLM       |
+----------------+    +----------------+    +------------------+

Adapter pattern - each layer has swappable implementations:

Channels: Telegram (telegraf), WebSocket (widget), WhatsApp (Twilio)
LLM: Claude (Anthropic API) or hardcoded (keyword matching for testing)
Tools: MCP registry with DulceGestion API client

Tech Stack

TypeScript, Express, telegraf, ws, @anthropic-ai/sdk, @modelcontextprotocol/sdk, Voyage AI (embeddings), vitest

Quick Start

# Install
npm install

# Configure
cp .env.example .env
# Edit .env with your keys

# Index documentation for RAG
npm run index-docs

# Run
npm run dev

Environment Variables

| Variable | Description | |----------|-------------| | TELEGRAM_TOKEN | Bot token from @BotFather | | ANTHROPIC_API_KEY | Claude API key | | VOYAGE_API_KEY | Voyage AI key (for embeddings) | | DULCEGESTION_API_URL | DulceGestion API endpoint | | LLM_ADAPTER | claude or hardcoded | | PORT | HTTP server port (default: 3002) | | SESSION_TTL_MINUTES | Chat session timeout | | WIDGET_ALLOWED_ORIGIN | CORS origin for widget |

Scripts

| Script | Description | |--------|-------------| | npm run dev | Start with hot reload | | npm start | Start in production | | npm test | Run tests | | npm run index-docs | Generate RAG embeddings from docs/flows/ | | npm run mcp | Start MCP stdio server (for Claude Desktop/Code) |

MCP Server

Use with Claude Desktop or Claude Code:

{
  "mcpServers": {
    "dulcegestion": {
      "command": "npx",
      "args": ["tsx", "src/mcp/server.ts"],
      "cwd": "/path/to/dulcechat",
      "env": {
        "DULCEGESTION_API_URL": "http://localhost:3001/api",
        "DULCEGESTION_AUTH_TOKEN": "your-jwt-token"
      }
    }
  }
}

Embeddable Widget

Add to any page:

<script src="https://your-server/dulcechat/widget.js" data-token="USER_JWT"></script>

Project Structure

src/
  channels/        # Messaging adapters (Telegram, Web, WhatsApp)
  llm/             # LLM adapters (Claude, hardcoded)
  mcp/             # MCP tools and server
    tools/         # Individual tool implementations
  rag/             # RAG system (chunker, embeddings, retriever)
  session/         # In-memory session store with TTL
  engine.ts        # Core orchestrator
  index.ts         # Entry point
docs/flows/        # User documentation for RAG indexing
widget/            # Embeddable chat widget (HTML + JS)

Adding New Tools

Create src/mcp/tools/your-tool.ts implementing McpTool
Register it in src/index.ts
Automatically available in Caramelo, Claude Desktop, and Claude Code

Caramelo MCP Server