Talqui Plugin Boilerplate

A starter kit for building plugins that bridge your systems to the Talqui AI-powered customer service platform.

---

Table of Contents

• What is Talqui?
• What is a Talqui Plugin?
• Why this boilerplate?
• How your plugin reaches the Talqui virtual agent
• Quick start
• Inspecting your MCP tools
• Project layout
• Submitting your plugin to Talqui
• Documentation
• License

---

What is Talqui?

Talqui is an omni-channel customer service platform that unifies conversations across channels (WhatsApp, Instagram, Telegram, marketplace inboxes, custom channels, etc.) and provides a virtual AI agent that handles attendance by following the procedures you define.

You do not need to host or rewrite any part of Talqui to extend it — Talqui ships with a plugin architecture so that companies and individual developers can plug their own systems into the platform without touching the Talqui core.

What is a Talqui Plugin?

A plugin is a self-contained service that lives in your infrastructure and exposes a contract Talqui understands. From Talqui's perspective, a plugin is a remote address Talqui can call to retrieve information, perform actions, or hand control over to during a conversation.

A plugin is the bridge between your domain (databases, ERPs, CRMs, ticketing systems, marketplaces, billing, e-commerce — anything you already run internally) and the Talqui platform. When a customer asks the virtual agent "what's the status of my order?", Talqui hands the request to your plugin — your plugin replies — Talqui delivers the answer back to the customer. You stay in control of the data and the integration logic; Talqui handles the conversation, the channels, and the agent.

Why this boilerplate?

You are not required to use this boilerplate. You can implement a Talqui-compatible plugin in any language or framework — what matters is exposing the right HTTP/MCP contracts to Talqui.

This repository exists to save you that work. It is an opinionated, production-shaped starting point that already wires up everything Talqui expects: an Express HTTP server, an MCP (Model Context Protocol) server, the registration handshake with the Talqui RTM channel, a clean-architecture skeleton you can extend, and a working demo (the in-memory "Ice Cream Shop") that proves end-to-end behavior without any external dependency.

You clone it, replace the demo domain with your own business logic, point Talqui at the resulting URL, and ship.

How your plugin reaches the Talqui virtual agent

Once your plugin is registered with Talqui, its MCP tools become first-class actions inside Talqui's procedure editor. Every tool you expose appears as a building block the virtual agent can call:

• Authors of attendance procedures can drag your tools into the flow editor and use their inputs/outputs like any other Talqui block.
• The virtual agent automatically discovers the tools through MCP tools/list and decides when to invoke them while running a procedure. The agent reads your tool descriptions and parameter schemas (the description and Zod .describe() annotations) to understand what each tool does — write them as if you were writing a tooltip for a human operator.
• Your HTTP routes are available to procedures and to embedded UI components (when you ship them) for direct integration calls outside the agent path.

In short: the moment your MCP server is reachable by Talqui and your tools are listed, the platform's AI agent gains access to whatever capabilities your tools represent.

Quick start

# 1. Clone and install
git clone https://github.com/talqui-oss/talqui-plugin-example.git
cd talqui-plugin-boilerplate
pnpm install

# 2. Create your local env from the example
cp apps/api/.env.example apps/api/.env

# 3. Run the dev server
pnpm dev

The HTTP server starts on http://localhost:9050. The MCP endpoint is available at POST http://localhost:9050/mcp. With no Talqui credentials configured, the demo still runs in full — you can hit the routes and call the tools immediately to see what shape the integration takes.

# Smoke-test the HTTP API
curl http://localhost:9050/                                 # heartbeat
curl http://localhost:9050/v1/healthcheck                   # provider health
curl -X POST http://localhost:9050/v1/flavors/search \
     -H 'content-type: application/json' \
     -d '{"field":"name","value":"choc"}'

Inspecting your MCP tools

Before you hand your MCP endpoint to Talqui, you should validate the tools locally with the official MCP Inspector. The inspector is a visual debugger that connects to your running MCP server, lists every tool you exposed, and lets you call them with arbitrary inputs to verify the response.

Open two terminals:

# Terminal 1 — run the API
pnpm dev

# Terminal 2 — launch the inspector
pnpm mcp:inspect

pnpm mcp:inspect is wired into Turborepo and forwards to apps/api/package.json. It opens the inspector in your browser pre-configured to connect to http://localhost:9050/mcp (see apps/api/mcp.json).

Test every tool you intend to ship. When the Talqui homologation team receives your MCP endpoint, they will run the same kind of validation against each of your tools to confirm they behave correctly under the platform's procedure runner — so the safer your locally tested set is, the smoother the homologation review will be.

Project layout

talqui-plugin-boilerplate/
├── apps/
│   ├── api/                # ← The plugin backend (Express + MCP server)
│   │   ├── src/
│   │   │   ├── @application/      # Domain layer (entities, use cases, services)
│   │   │   ├── @infra/            # Infrastructure (routes, controllers, MCP tools)
│   │   │   ├── server/            # Inline HTTP + MCP server framework
│   │   │   └── index.ts           # Entry point
│   │   ├── mcp.json               # MCP Inspector configuration
│   │   └── README.md              # Full API guide — start here when coding
│   └── widget/             # ← Sidebar UI (Vue 3 + Vite, embedded as an iframe)
│       ├── src/
│       │   ├── utils/             # Host event dialogue (pluginBridge.ts) + helpers
│       │   ├── components/ui/     # shadcn-vue primitives (Tailwind + Lucide)
│       │   ├── views/             # Routed screens
│       │   └── main.ts            # Entry point (mounts, then opens the host channel)
│       └── README.md              # Full widget guide
├── packages/                       # Shared monorepo packages (lint config)
├── turbo.json                      # Monorepo task pipelines
└── pnpm-workspace.yaml

Backend work happens inside apps/api/ — see apps/api/README.md for adding tools/routes and replacing the demo domain. The optional operator UI lives in apps/widget/ — see apps/widget/README.md.

Submitting your plugin to Talqui

The handoff to Talqui is intentionally minimal:

1. Replace the in-memory Ice Cream Shop demo with your domain (tools + routes that map to your real systems).
2. Validate everything with the MCP Inspector as described above.
3. Deploy the API to your own infrastructure (any container host, VPS, serverless container service, or PaaS works — Node ≥ 24 is the only runtime requirement).
4. Send the Talqui team the public address of your /mcp endpoint plus any authentication credentials your plugin requires.
5. Talqui's homologation team validates each tool end-to-end and, when everything passes, your plugin becomes available inside the platform's procedure editor.

From that point on, every Talqui tenant subscribed to your plugin can use its tools in procedures and have the virtual agent invoke them during attendances.

Documentation

• 📘 apps/api/README.md — full developer guide for the API
• 🖼️ apps/widget/README.md — the sidebar widget UI (Vue 3 + shadcn-vue)
• 📐 AGENTS.md — high-level architectural map (also referenced by AI coding assistants)
• 🌐 docs.talqui.chat — Talqui platform documentation
• 🔐 Authentication — how plugin tokens and plugin connection tokens work
• 📨 Session Start — opening conversations from your plugin
• 🤖 Chatbot / Procedure builder — where your MCP tools will appear
• 📬 REST API Postman collection
• ⚡ RTM API — the Real-Time Messages channel your plugin can join

License

ISC — free for commercial use. Build something cool.